Mobile application API definition (1.0.0)

Download OpenAPI specification:Download

AppLabel

Get app download url

Return application store url of the requested app label

query Parameters

app_label

required

string

The name of the application white label calling the route.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": [{"android_store_url": "string",
"ios_store_url": "string"
}
]
}

Badges

Get user's badges

Return the badges of the user making the request.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"badge_id": 1,
"name": "string"
}
]
}

Link badge

Begin the linking process of a new badge.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info of the new badge to link.

cluster_id required	integer >= 1 Identifier of the cluster on which the user will put his badge to link it to his account.
name required	string <= 30 The display name for this badge.
spot_id	integer >= 1 Identifier of the spot on which the user will put his badge to link it to his account. Only for station v6.

Responses

Request samples

Payload

Content type

application/json

{"cluster_id": 1,
"name": "string",
"spot_id": 1
}

Response samples

Content type

application/json

{"code": 0
}

Update name

Update the name of a badge.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info of the badge.

badge_id required	integer >= 1 The identifier of the badge to edit.
name required	string <= 30 The new display name of the badge.

Responses

Request samples

Payload

Content type

application/json

{"badge_id": 1,
"name": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Delete a badge

Delete/unlink a badge of the user.

Authorizations:

Authenticated

query Parameters

badge_id

required

integer >= 1

The identifier of the badge to delete.

Responses

Response samples

Content type

application/json

{"code": 0
}

BankGuarantees

Get user bank guarantees

Get the list of usable or currently used bank guarantees.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"id": "string",
"amount": "350.000",
"currency": "string",
"date": "2019-08-24T14:15:22Z",
"being_used": true,
"exp_date": "2019-08-24T14:15:22Z",
"refund_date": "2019-08-24T14:15:22Z"
}
]
}

Create user bank guarantee

Create a new bank guarantee for the user.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info about the bank guarantee to create.

vehicle_id required	integer >= 1 The identifier of the vehicle we want to create a bank guarantee for.
payment_method_id	integer >= 1 The identifier of the payment method to use for the bank guarantee.
user_payment_method_id	integer >= 1 The identifier of the user's payment method instance to use for the bank guarantee.
keep_after_trip	boolean When true, the guarantee will be kept for three days, otherwise its released after the trip ends.
payment_method_parameters	object The payment method specific parameters.

Responses

Request samples

Payload

Content type

application/json

{"vehicle_id": 1,
"payment_method_id": 1,
"user_payment_method_id": 1,
"keep_after_trip": true,
"payment_method_parameters": { }
}

Response samples

Content type

application/json

Example

CodeSuccess

{"code": 0
}

Get payment methods for bank guarantee

Return all available payment methods usable by the user to make a bank guarantee for the given vehicle.

Authorizations:

Authenticated

query Parameters

vehicle_id

required

integer >= 1

Identifier of the vehicle to make a bank guarantee for.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string",
"instances": [{"id": 1,
"details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
}
}
]
}
],
"providers_setup_info": {"stripe": {"public_key": "string"
}
}
}

Cancel bank guarantee

Cancel a bank guarantee before its automatic cancellation. This is for users which are in bank that withdraw the amount of the pre-authorization instead of just blocking it.

Authorizations:

Authenticated

path Parameters

id

required

string [ 1 .. 128 ] characters

The identifier of the bank guarantee to cancel.

Responses

Response samples

Content type

application/json

{"code": 0
}

Chats

Get chat channels

Return the list of reports, or chat channels, that the user made.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"report_id": 1,
"message": "string",
"sender": "string",
"date": "2019-08-24T14:15:22Z",
"report_date": "2019-08-24T14:15:22Z",
"resolved": true,
"unread": true
}
]
}

Get a chat channel

Return a chat channel.

Authorizations:

Authenticated

path Parameters

report_id

required

integer >= 1

The identifier of the report to get.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"report_id": 1,
"message": "string",
"sender": "string",
"date": "2019-08-24T14:15:22Z",
"report_date": "2019-08-24T14:15:22Z",
"resolved": true,
"unread": true
}
}

Upload image

Upload an image into a new chat message.

Authorizations:

Authenticated

path Parameters

report_id

required

integer >= 1

The identifier of the report we want to add the image to.

Request Body schema: multipart/form-data
required

The picture to upload.

chat_image

required

string <binary>

The picture file data.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"id": "string",
"date": "string",
"url": "string"
}
}

Clusters

Get clusters

Return clusters accessible by the user on a given area.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] The latitude of the center of the area in which to get clusters.
lng required	number [ -180 .. 180 ] The longitude of the center of the area in which to get clusters.
latDeg required	number [ -90 .. 90 ] The number of latitude degree of the area in which to get clusters. Can be compared to the height of the area.
lngDeg required	number [ -180 .. 180 ] The number of longitude degree of the area in which to get clusters. Can be compared to the width of the area.
lang	string^[a-z]{2}$ The language (ISO 639-1) to use for the description localization. Defaults to english.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"cluster_id": 1,
"latitude": 48.5900027,
"longitude": 7.7531998,
"name": "Knot Headquarters",
"available_vehicles": 0,
"total_spots": 0,
"free_spots": 0,
"cluster_is_down": true,
"network_id": 1,
"logo_url": "http://example.com",
"soon_to_be_available": true,
"commissioning_date": "2019-08-24T14:15:22Z",
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"description": "string",
"cluster_is_accessible": true,
"has_badge_reader": true,
"balancing_type": "donor"
}
]
}

Create cluster

Create a new cluster.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Info on the cluster to create.

lat required	number [ -90 .. 90 ] Latitude part of the location.
lng required	number [ -180 .. 180 ] Longitude part of the location.
name required	string [ 1 .. 50 ] characters Display name of this cluster.
network_id required	integer >= 1 Identifier of the network in which this cluster is into.

Responses

Request samples

Payload

Content type

application/json

{"lat": 48.5900027,
"lng": 7.7531998,
"name": "Knot Headquarters",
"network_id": 1
}

Response samples

Content type

application/json

{"code": 0
}

Get public clusters

Return clusters accessible by anyone on a given area.

query Parameters

lat required	number [ -90 .. 90 ] The latitude of the center of the area in which to get clusters.
lng required	number [ -180 .. 180 ] The longitude of the center of the area in which to get clusters.
latDeg required	number [ -90 .. 90 ] The number of latitude degree of the area in which to get clusters. Can be compared to the height of the area.
lngDeg required	number [ -180 .. 180 ] The number of longitude degree of the area in which to get clusters. Can be compared to the width of the area.
lang	string^[a-z]{2}$ The language (ISO 639-1) to use for the description localization. Defaults to english.
network_id	integer >= 1 A network identifier of which to get public clusters.
app_label required	string The name of the application white label calling the route.

Responses

Response samples

200
400
410
500

Content type

application/json

{"code": 0,
"data": [{"cluster_id": 1,
"latitude": 48.5900027,
"longitude": 7.7531998,
"name": "Knot Headquarters",
"available_vehicles": 0,
"total_spots": 0,
"free_spots": 0,
"cluster_is_down": true,
"network_id": 1,
"logo_url": "http://example.com",
"soon_to_be_available": true,
"commissioning_date": "2019-08-24T14:15:22Z",
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"description": "string"
}
]
}

Get closest clusters

Return the 20 closest clusters accessible by logged in users on a given area.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] The latitude of the center of the area in which to get clusters.
lng required	number [ -180 .. 180 ] The longitude of the center of the area in which to get clusters.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"cluster_id": 1,
"latitude": 48.5900027,
"longitude": 7.7531998,
"name": "Knot Headquarters",
"available_vehicles": 0,
"total_spots": 0,
"free_spots": 0,
"cluster_is_down": true,
"network_id": 1,
"logo_url": "http://example.com",
"cluster_is_accessible": true,
"distance": 0,
"has_badge_reader": true
}
]
}

Get cluster by id

Return the details of a cluster.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The cluster id.

query Parameters

lang	string^[a-z]{2}$ The language (ISO 639-1) to use for the description localization. Defaults to english.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"cluster_id": 1,
"latitude": 48.5900027,
"longitude": 7.7531998,
"name": "Knot Headquarters",
"available_vehicles": 0,
"total_spots": 0,
"free_spots": 0,
"cluster_is_down": true,
"network_id": 1,
"logo_url": "http://example.com",
"soon_to_be_available": true,
"commissioning_date": "2019-08-24T14:15:22Z",
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"description": "string",
"cluster_is_accessible": true,
"has_badge_reader": true,
"balancing_type": "donor"
}
}

Get cluster spots

Return list of spot of the given cluster.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the cluster.

Responses

Response samples

200
400
410
500

Content type

application/json

{"code": 0,
"data": [{"spot_id": 1,
"station_id": 1,
"displayed_number": 1,
"in_maintenance": true,
"is_accessible": true
}
]
}

Get cluster vehicles

Return list of vehicle of the given cluster.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the cluster.

Responses

Response samples

200
400
410
500

Content type

application/json

{"code": 0,
"data": [{"vehicle_id": 1,
"serial_number": "string",
"battery_level": 100,
"avg_max_range": 0,
"vehicle_type": "kick-scooter",
"vehicle_online": true,
"spot_id": 1,
"station_id": 1,
"displayed_number": 1,
"in_maintenance": true,
"is_accessible": true
}
]
}

Update cluster name

Update the cluster name.

Authorizations:

(AuthenticatedPermissions)

path Parameters

id

required

integer >= 1

The identifier of the cluster we want to update.

Request Body schema: application/json
required

Info on the cluster to update.

name	string [ 1 .. 50 ] characters The new name for the cluster.

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Change max unlock distance

Update the max unlock distance for a specific cluster.

Authorizations:

(AuthenticatedPermissions)

path Parameters

id

required

integer >= 1

The identifier of the cluster we want to update.

Request Body schema: application/json
required

Info on the cluster to change unlock distance.

new_distance

required

integer or null [ 10 .. 1000 ]

New max unlock distance.

Responses

Request samples

Payload

Content type

application/json

{"new_distance": 10
}

Response samples

Content type

application/json

{"code": 0
}

Consents

Get user's consents

Return consents given by the user making the request.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"type": "emails.networkstatus",
"name": "string",
"value": true
}
]
}

Update consents

Update the user's consents.

Authorizations:

Authenticated

Request Body schema: application/json
required

New consents values.

required

object

Responses

Request samples

Payload

Content type

application/json

{"consents": {"emails.networkstatus": true,
"emails.promotional": true
}
}

Response samples

Content type

application/json

{"code": 0
}

Get consents types

Return all consents types.

Authorizations:

Authenticated

query Parameters

lang

required

string^[a-z]{2}$

The language (ISO 639-1) to use translating the consents name.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"type": "emails.networkstatus",
"name": "string",
"value": true
}
]
}

Countries

Get countries

Return all countries name, iso code and phone prefixes.

Responses

Response samples

200
500

Content type

application/json

{"code": 0,
"data": [{"country_id": 1,
"name": "string",
"iso_2": "st",
"iso_3": "str",
"phone_prefix": "string"
}
]
}

Get country

Return a country from the given position.

query Parameters

lat required	number [ -90 .. 90 ] Latitude of where to search the country.
lng required	number [ -180 .. 180 ] Longitude of where to search the country.

Responses

Response samples

200
400
404
500

Content type

application/json

{"code": 0,
"data": {"country_id": 1,
"name": "string",
"iso_2": "st",
"iso_3": "str",
"phone_prefix": "string"
}
}

Get country from ip

Return a country from the request ip.

Responses

Response samples

200
404
500

Content type

application/json

{"code": 0,
"data": {"country_id": 1,
"name": "string",
"iso_2": "st",
"iso_3": "str",
"phone_prefix": "string"
}
}

Discounts

Get discounts

Return discounts used by the user.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"discount_id": 1,
"name": "string",
"type": 1,
"stop_date": "2019-08-24",
"code": "string",
"data": 0,
"currency": "string",
"active": true
}
]
}

Get shop discount

Return discounts usable by the user for the shop.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of the user to get discounts available for offers on the nearest network.
lng required	number [ -180 .. 180 ] Longitude of the user to get discounts available for offers on the nearest network.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"discount_id": 1,
"name": "string",
"type": 1,
"stop_date": "2019-08-24",
"code": "string",
"data": 0,
"currency": "string"
}
]
}

Use discount

Use a discount code.

Authorizations:

Authenticated

Request Body schema: application/json
required

The code of the discount and the position of the user.

lat required	number [ -90 .. 90 ] Latitude of the user to check that the discount is available on the nearest network.
lng required	number [ -180 .. 180 ] Longitude of the user to check that the discount is available on the nearest network.
code required	string non-empty Discount code to identify which discount we try to use.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180,
"code": "string"
}

Response samples

Content type

application/json

{"code": 0,
"data": {"discount_id": 1,
"name": "string",
"type": 1,
"stop_date": "2019-08-24",
"code": "string",
"data": 0,
"currency": "string"
}
}

Emails

Request email change

Send an email containing a confirmation link to change the user's email address to a new one.

Authorizations:

Authenticated

Request Body schema: application/json
required

New email.

email

required

string <email>

The new email address to send a confirmation email to.

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com"
}

Response samples

Content type

application/json

{"code": 0
}

Send confirmation email

Send again an email containing a confirmation link to confirm the user's email address. The token used for authentication is given by the login route with the code 7 (email not confirmed).

Authorizations:

Authenticated

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0
}

Confirm email change

Change the user's email by the new specified one.

Request Body schema: application/json
required

Info to authenticate the email change.

email_token required	string = 10 characters The mail change token.
email required	string <email> The new email address.

Responses

Request samples

Payload

Content type

application/json

{"email_token": "stringstri",
"email": "user@example.com"
}

Response samples

200
400
401
410
500

Content type

application/json

{"code": 0
}

Confirm email

Confirm the email of the user using the validation token.

Request Body schema: application/json
required

Info to authenticate the email conformation.

token

required

string = 10 characters

The mail change token.

Responses

Request samples

Payload

Content type

application/json

{"token": "stringstri"
}

Response samples

200
400
500

Content type

application/json

{"code": 0,
"android_store_url": "string",
"ios_store_url": "string",
"label_name": "string",
"email": "user@example.com"
}

Faq

Get faq

Get the content of the faq.

query Parameters

lang required	string = 2 characters The lang in which to get the faq localized.
app_label	string The name of the application white label calling the route.

Responses

Response samples

200
500

Content type

application/json

{"code": 0,
"data": [{"key": "string",
"name": "string",
"translated": true,
"sort_order": 0,
"sub_categories": [{"key": "string",
"name": "string",
"translated": true,
"sort_order": 0,
"is_spacer": true,
"replacements": ["app-label"
],
"contents": [{"key": "string",
"content": "string",
"translated": true,
"sort_order": 0,
"type": "text",
"bold": true,
"margin": "string",
"text_color": "primary",
"bullet_color": "primary",
"replacements": ["app-label"
]
}
]
}
]
}
]
}

GlobalAnnouncement

Get global announcement

Get the ongoing global announcement in the language requested if available.

query Parameters

lang

required

string = 2 characters

The lang in which to get the announcement.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": {"announcement": "string"
}
}

Login

Log in a user with it's Knot account.

Request Body schema: application/json
required

Credentials of the user.

email required	string <email> Email of the user.
password required	string [ 8 .. 255 ] characters Password of the user.
scope	string Enum: "app" "dashboard" For what the token will be used.
	object (LoginDevice) Device being used to connect.
app_label required	string [ 1 .. 20 ] characters Name of the app label making the request.

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"password": "stringst",
"scope": "app",
"device": {"id": "string",
"os": "Android",
"model": "string",
"app_version": "string"
},
"app_label": "string"
}

Response samples

200
400
401
403
500

Content type

application/json

Example

Login

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1,
"permissions": [{"perm_key": "string",
"write": true,
"ou": {"id": 1,
"networks": [1
],
"clusters": [{"id": 1,
"network": 1
}
],
"app_labels": [1
],
"organizations": [1
]
}
}
]
}

Check token

Check the validity of a token and return the user's permissions.

Authorizations:

Authenticated

Request Body schema: application/json
required

Information on the device used to login.

object (LoginDevice)

Device being used to connect.

Responses

Request samples

Payload

Content type

application/json

{"device": {"id": "string",
"os": "Android",
"model": "string",
"app_version": "string"
}
}

Response samples

Content type

application/json

{"code": 0,
"permissions": [{"perm_key": "string",
"write": true,
"ou": {"id": 1,
"networks": [1
],
"clusters": [{"id": 1,
"network": 1
}
],
"app_labels": [1
],
"organizations": [1
]
}
}
]
}

Refresh token

Request a new access token with the refresh token. You need to use the refresh token instead of the access token in the Authorization header. The given token will be invalidated and you will get a new one.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"access_token": "string",
"refresh_token": null
}

Reset password

Send an email to reset a user's password.

Request Body schema: application/json
required

Info on the user who want to reset its password.

email required	string <email> Account's email which we want to reset the password.
app_label required	string [ 1 .. 20 ] characters Name of the app label making the request.

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"app_label": "string"
}

Response samples

200
400
500

Content type

application/json

{"code": 0
}

2FA Login

Second factor check for users with 2FA, route to call if a login route returns the code 146 (TwoFactorRequired). The authentication token is the one given by the login route that returned the code 146.

Request Body schema: application/json
required

Info to complete the authentication's second factor.

mfa_token required	string/^\d{6}$/ A token given by an OTP app for the generated key.
	object (LoginDevice) Device being used to connect.

Responses

Request samples

Payload

Content type

application/json

{"mfa_token": "string",
"device": {"id": "string",
"os": "Android",
"model": "string",
"app_version": "string"
}
}

Response samples

Content type

application/json

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1,
"permissions": [{"perm_key": "string",
"write": true,
"ou": {"id": 1,
"networks": [1
],
"clusters": [{"id": 1,
"network": 1
}
],
"app_labels": [1
],
"organizations": [1
]
}
}
]
}

Disable 2FA

Disable two factors authentication for the user.

Authorizations:

Authenticated

Responses

Response samples

Content type

application/json

{"code": 0
}

Begin 2FA Setup

Begin enabling two factors authentication by generating a key and a url for an otp application. User should save the key in its app then call the login/2fa/verify route.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"key": "KVKGQ32EK5BEKNTUNRTESTDSOU",
"key_url": "otpauth://totp/Knot%3AArlo_Stehr50%40yahoo.com?secret=KVKGQ32EK5BEKNTUNRTESTDSOU",
"token": "string"
}

End 2FA Setup

End the two factors authentication setup by verifying one code generated by an OTP app and the token given in the login/2fa/generate route.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info from the OTP application and given by the begin route.

token required	string Token given in the login/2fa/generate route.
mfa_token required	string/^\d{6}$/ A token given by an OTP app for the generated key.

Responses

Request samples

Payload

Content type

application/json

{"token": "string",
"mfa_token": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Apple login

Login with an Apple account.

Request Body schema: application/json
required

Info to authenticate with an Apple account.

token required	string Apple's idToken.
scope	string Enum: "app" "dashboard" For what the token will be used.
	object (LoginDevice) Device being used to connect.
app_label required	string [ 1 .. 20 ] characters Name of the app label making the request.
lang	string/^[a-zA-Z]{2}$/ The user's language. Defaults to English.

Responses

Request samples

Payload

Content type

application/json

{"token": "string",
"scope": "app",
"device": {"id": "string",
"os": "Android",
"model": "string",
"app_version": "string"
},
"app_label": "string",
"lang": "string"
}

Response samples

200
400
403
500

Content type

application/json

Example

Login

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1,
"permissions": [{"perm_key": "string",
"write": true,
"ou": {"id": 1,
"networks": [1
],
"clusters": [{"id": 1,
"network": 1
}
],
"app_labels": [1
],
"organizations": [1
]
}
}
]
}

Facebook login

Login with a Facebook account.

Request Body schema: application/json
required

Info to authenticate with a Facebook account.

token required	string Facebook's access token.
scope	string Enum: "app" "dashboard" For what the token will be used.
	object (LoginDevice) Device being used to connect.
app_label required	string [ 1 .. 20 ] characters Name of the app label making the request.
lang	string/^[a-zA-Z]{2}$/ The user's language. Defaults to English.

Responses

Request samples

Payload

Content type

application/json

{"token": "string",
"scope": "app",
"device": {"id": "string",
"os": "Android",
"model": "string",
"app_version": "string"
},
"app_label": "string",
"lang": "string"
}

Response samples

200
400
403
500

Content type

application/json

Example

Login

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1,
"permissions": [{"perm_key": "string",
"write": true,
"ou": {"id": 1,
"networks": [1
],
"clusters": [{"id": 1,
"network": 1
}
],
"app_labels": [1
],
"organizations": [1
]
}
}
]
}

Google login

Login with a google account.

Request Body schema: application/json
required

Info to authenticate with a Google account.

token required	string Google's idToken.
scope	string Enum: "app" "dashboard" For what the token will be used.
	object (LoginDevice) Device being used to connect.
app_label required	string [ 1 .. 20 ] characters Name of the app label making the request.
lang	string/^[a-zA-Z]{2}$/ The user's language. Defaults to English.

Responses

Request samples

Payload

Content type

application/json

{"token": "string",
"scope": "app",
"device": {"id": "string",
"os": "Android",
"model": "string",
"app_version": "string"
},
"app_label": "string",
"lang": "string"
}

Response samples

200
400
403
500

Content type

application/json

Example

Login

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1,
"permissions": [{"perm_key": "string",
"write": true,
"ou": {"id": 1,
"networks": [1
],
"clusters": [{"id": 1,
"network": 1
}
],
"app_labels": [1
],
"organizations": [1
]
}
}
]
}

Logout

Logout from a device or all device if is are specified.

Authorizations:

Authenticated

Request Body schema: application/json
required

The device to logout.

device_id

string [ 1 .. 50 ] characters

Unique identifier of the device disconnecting. If omitted all user's devices are disconnected and sessions are invalidated.

Responses

Request samples

Payload

Content type

application/json

{"device_id": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Maintenances

Get maintenances types

Returns all available maintenance types.

Authorizations:

(AuthenticatedPermissions)

query Parameters

lang

required

string = 2 characters

The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"type_key": "string",
"target_type": "station",
"severity": "info",
"type_name": "string",
"deletion_date": "string",
"creation_date": "string"
}
]
}

Get maintenances of spot

Returns all the ongoing maintenances of a spot.

Authorizations:

(AuthenticatedPermissions)

query Parameters

spot_id required	integer >= 1 The identifier of the spot we want to get the maintenances of.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
]
}
]
}

Add spot maintenance

Create a new maintenance for a spot.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Info on the maintenance to add.

maintenance_type required	string [ 1 .. 50 ] characters The type of maintenance to add.
comment	string [ 1 .. 1024 ] characters An optional comment for the maintenance.
severity	string Enum: "info" "low" "high" The severity of this maintenance. If not provided we default on the severity of the maintenance type.
spot_id required	integer >= 0 The identifier of the spot on which to add the maintenance.

Responses

Request samples

Payload

Content type

application/json

{"maintenance_type": "string",
"comment": "string",
"severity": "info",
"spot_id": 0
}

Response samples

Content type

application/json

{"code": 0,
"data": {"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
]
}
}

Get maintenances history of spot

Returns all the resolved maintenances of a spot.

Authorizations:

(AuthenticatedPermissions)

query Parameters

spot_id required	integer >= 1 The identifier of the spot we want to get the maintenances of.
last_maintenance_id	integer >= 1 The identifier of the last maintenance we have, to get the maintenances coming after it.
direction	string Enum: "ASC" "DESC" The direction in which to sort the maintenances.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
],
"stop_date": "string",
"stopped_by": "string",
"stopped_by_uid": 1
}
]
}

Get maintenances of vehicle

Returns all the ongoing maintenances of a vehicle.

Authorizations:

(AuthenticatedPermissions)

query Parameters

vehicle_id	integer >= 1 The identifier of the vehicle we want to get the maintenances of. You need to specify at least one of the parameters.
serial_number	string [ 6 .. 10 ] characters The serial number of the vehicle we want to get the maintenances of. You need to specify at least one of the parameters.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
]
}
]
}

Add vehicle maintenance

Create a new maintenance for a vehicle.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Info on the maintenance to add.

maintenance_type required	string [ 1 .. 50 ] characters The type of maintenance to add.
comment	string [ 1 .. 1024 ] characters An optional comment for the maintenance.
severity	string Enum: "info" "low" "high" The severity of this maintenance. If not provided we default on the severity of the maintenance type.
vehicle_id	integer >= 1 The identifier of the vehicle on which to add the maintenance. You need to specify at least one of the parameters.
serial_number	string [ 6 .. 10 ] characters The serial number of the vehicle on which to add the maintenance. You need to specify at least one of the parameters.

Responses

Request samples

Payload

Content type

application/json

{"maintenance_type": "string",
"comment": "string",
"severity": "info",
"vehicle_id": 1,
"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0,
"data": {"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
]
}
}

Get maintenances history of vehicle

Returns all the resolved maintenances of a vehicle.

Authorizations:

(AuthenticatedPermissions)

query Parameters

vehicle_id	integer >= 1 The identifier of the vehicle we want to get the maintenances of. You need to specify at least one of the parameters.
serial_number	string [ 6 .. 10 ] characters The serial number of the vehicle we want to get the maintenances of. You need to specify at least one of the parameters.
last_maintenance_id	integer >= 1 The identifier of the last maintenance we have, to get the maintenances coming after it.
direction	string Enum: "ASC" "DESC" The direction in which to sort the maintenances.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
],
"stop_date": "string",
"stopped_by": "string",
"stopped_by_uid": 1
}
]
}

Get maintenances of station

Returns all the ongoing maintenances of a station. This only returns the maintenances concerning the station as a whole and not its spots or vehicles.

Authorizations:

(AuthenticatedPermissions)

query Parameters

station_id required	integer >= 1 The identifier of the station we want to get the maintenances of.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
]
}
]
}

Add station maintenance

Create a new maintenance for a station.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Info on the maintenance to add.

maintenance_type required	string [ 1 .. 50 ] characters The type of maintenance to add.
comment	string [ 1 .. 1024 ] characters An optional comment for the maintenance.
severity	string Enum: "info" "low" "high" The severity of this maintenance. If not provided we default on the severity of the maintenance type.
station_id required	integer >= 0 The identifier of the station on which to add the maintenance.

Responses

Request samples

Payload

Content type

application/json

{"maintenance_type": "string",
"comment": "string",
"severity": "info",
"station_id": 0
}

Response samples

Content type

application/json

{"code": 0,
"data": {"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
]
}
}

Get maintenances history of station

Returns all the resolved maintenances of a station. This only returns the maintenances concerning the station as a whole and not its spots or vehicles.

Authorizations:

(AuthenticatedPermissions)

query Parameters

station_id required	integer >= 1 The identifier of the station we want to get the maintenances of.
last_maintenance_id	integer >= 1 The identifier of the last maintenance we have, to get the maintenances coming after it.
direction	string Enum: "ASC" "DESC" The direction in which to sort the maintenances.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"maintenance_id": 1,
"spot_id": 1,
"vehicle_id": 1,
"station_id": 1,
"maintenance_type": "string",
"comment": "string",
"start_date": "string",
"started_by": "string",
"started_by_uid": 1,
"severity": "info",
"automatic_code_description": "string",
"pictures": ["http://example.com"
],
"stop_date": "string",
"stopped_by": "string",
"stopped_by_uid": 1
}
]
}

Get maintenances overview of cluster

Returns the list of spot of the cluster with the a count of all maintenances on them.

Authorizations:

(AuthenticatedPermissions)

query Parameters

cluster_id

required

integer >= 1

The identifier of the cluster we want to get the overview of.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"stations": [{"station_id": 1,
"station_maintenances": {"info_count": 0,
"low_count": 0,
"high_count": 0
},
"spots": [{"spot_id": 1,
"contained_vehicle_id": 1,
"serial_number": "string",
"station_id": 1,
"displayed_number": 0,
"lock_status": 0,
"vehicle_maintenances": {"info_count": 0,
"low_count": 0,
"high_count": 0
},
"spot_maintenances": {"info_count": 0,
"low_count": 0,
"high_count": 0
},
"vehicle_type": { }
}
]
}
],
"vehicles": [{"vehicle_id": 1,
"serial_number": "string",
"vehicle_maintenances": {"info_count": 0,
"low_count": 0,
"high_count": 0
},
"vehicle_type": "kick-scooter"
}
]
}
}

Get count maintenances of clusters

Returns the list of clusters given with the maintenance count for each cluster.

Authorizations:

(AuthenticatedPermissions)

query Parameters

clusters

required

Array of integers[ items >= 1 ]

Examples:

clusters=5 - With one cluster id.
clusters=1,5,7 - With multiple cluster id.

Identifier of clusters of which to get the maintenance count.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"cluster_id": 1,
"maintenances": {"info_count": 0,
"low_count": 0,
"high_count": 0
}
}
]
}

Update maintenance

Update of the comment and severity of a maintenance.

Authorizations:

(AuthenticatedPermissions)

path Parameters

id

required

integer >= 1

The identifier of the maintenance we want to update.

Request Body schema: application/json
required

Info on the maintenance to update.

comment	string [ 1 .. 1024 ] characters The new comment for the maintenance.
severity	string Enum: "info" "low" "high" The new severity for the maintenance.

Responses

Request samples

Payload

Content type

application/json

{"comment": "string",
"severity": "info"
}

Response samples

Content type

application/json

{"code": 0
}

End or delete maintenance

Mark a maintenance as resolved or delete it.

Authorizations:

(AuthenticatedPermissions)

path Parameters

id

required

integer >= 1

The identifier of the maintenance we want to mark as resolved.

query Parameters

delete_from_history

boolean

When true, delete the maintenance from the history, otherwise it is marked as solved.

Responses

Response samples

Content type

application/json

{"code": 0
}

Link picture to maintenance

Upload a picture and link it to a maintenance.

Authorizations:

(AuthenticatedPermissions)

path Parameters

id

required

integer >= 1

The identifier of the maintenance we want to attach an image to.

Request Body schema: multipart/form-data
required

The picture to upload.

maintenance_picture

required

string <binary>

The picture file data.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"url": "string"
}
}

Map

Get map elements

Return clusters, free floating vehicles, user's rents and passes and virtual parking.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get map elements.
lng required	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get map elements.
latdeg required	number >= 0 Number of latitude degree of the area of which we want to get map elements.
lngdeg required	number >= 0 Number of longitude degree of the area of which we want to get map elements.
lang	string = 2 characters Language in which to get the localization, defaults to 'en'.

Responses

Response samples

Content type

application/json

{"code": 0,
"clusters": [{"cluster_id": 1,
"latitude": -90,
"longitude": -180,
"name": "string",
"available_vehicles": 0,
"total_spots": 0,
"free_spots": 0,
"cluster_is_down": true,
"network_id": 1,
"logo_url": "http://example.com",
"soon_to_be_available": true,
"commissioning_date": "2019-08-24T14:15:22Z",
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"description": "string",
"cluster_is_accessible": true,
"has_badge_reader": true
}
],
"vehicles": [{"vehicle_id": 1,
"serial_number": "string",
"latitude": -90,
"longitude": -180,
"connected": true,
"network_id": 1,
"battery_level": 100,
"vehicle_type": "kick-scooter",
"state": "rented",
"is_accessible": true,
"is_available": true,
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"has_freefloat_to_station_reward": true
}
],
"parkings": [{"virtual_parking_id": 1,
"cluster_id": 1,
"network_id": 1,
"shape": [[-180
]
],
"is_accessible": true
}
],
"rents": [{"vehicle_id": 1,
"serial_number": "string",
"free_floating": true,
"being_rented": true,
"displayed_number": 1,
"lock_status": 0,
"trip_id": 1,
"time_start": "2019-08-24T14:15:22Z",
"billing_time_stop": "2019-08-24T14:15:22Z",
"on_hold_since": "2019-08-24T14:15:22Z",
"on_hold_activated": true,
"network_id": 1,
"battery_level": 100,
"min_battery_to_slow_down": 100,
"min_battery_to_auto_lock": 100,
"avg_max_range": 0,
"external_locks": [{"external_lock_id": 1,
"model": "string",
"type": "u",
"code": "string"
}
]
}
],
"passes": [{"pass_id": 1,
"end_date": "2019-08-24T14:15:22Z",
"in_use": true
}
],
"networks": [{"network_id": 1,
"name": "string",
"logo_url": "http://example.com",
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"center_latitude": -90,
"center_longitude": -180,
"currency": "string",
"max_simultaneous_rented_vehicle": 1
}
],
"speed_zones": [{"speed_zone_id": 1,
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"max_speed": 0
}
]
}

Get public map elements

Return clusters, free floating vehicles and virtual parking publicly visible.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get map. elements.
lng required	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get map. elements.
latDeg required	number >= 0 Number of latitude degree of the area of which we want to get map. elements.
lngDeg required	number >= 0 Number of longitude degree of the area of which we want to get map. elements.
network_id	integer >= 1 Network id to filter clusters.
lang	string = 2 characters Language in which to get the localization, defaults to 'en'.
app_label required	string The name of the application white label calling the route.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"clusters": [{"cluster_id": 1,
"latitude": -90,
"longitude": -180,
"name": "string",
"available_vehicles": 0,
"total_spots": 0,
"free_spots": 0,
"cluster_is_down": true,
"network_id": 1,
"logo_url": "http://example.com",
"soon_to_be_available": true,
"commissioning_date": "2019-08-24T14:15:22Z",
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"description": "string"
}
],
"vehicle": [{"vehicle_id": 1,
"serial_number": "string",
"latitude": -90,
"longitude": -180,
"connected": true,
"network_id": 1,
"battery_level": 100,
"vehicle_type": "kick-scooter"
}
],
"parkings": [{"virtual_parking_id": 1,
"cluster_id": 1,
"network_id": 1,
"shape": [[-180
]
]
}
],
"networks": [{"network_id": 1,
"name": "string",
"logo_url": "http://example.com",
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"center_latitude": -90,
"center_longitude": -180,
"currency": "string",
"max_simultaneous_rented_vehicle": 1
}
],
"speed_zones": [{"speed_zone_id": 1,
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"max_speed": 0
}
]
}

Networks

Get networks

Return a list of networks. If lat, lng, latdeg and lngdeg are given this returns the networks in the defined area otherwise this returns all networks.

Authorizations:

Authenticated

query Parameters

lat	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get networks.
lng	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get networks.
latdeg	number >= 0 Number of latitude degree of the area of which we want to get networks.
lngdeg	number >= 0 Number of longitude degree of the area of which we want to get networks.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"network_id": 1,
"name": "string",
"logo_url": "http://example.com",
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"center_latitude": -90,
"center_longitude": -180,
"currency": "string",
"max_simultaneous_rented_vehicle": 1
}
]
}

Get public networks

Return a list of public networks. If lat, lng, latdeg and lngdeg are given this returns the public networks in the defined area otherwise this returns all public networks.

query Parameters

lat	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get public networks.
lng	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get public networks.
latdeg	number >= 0 Number of latitude degree of the area of which we want to get public networks.
lngdeg	number >= 0 Number of longitude degree of the area of which we want to get public networks.
app_label required	string The name of the application white label calling the route.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": [{"network_id": 1,
"name": "string",
"logo_url": "http://example.com",
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"center_latitude": -90,
"center_longitude": -180,
"currency": "string",
"max_simultaneous_rented_vehicle": 1
}
]
}

Get nearest networks

Return all networks ordered by distance.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of user's position.
lng required	number [ -180 .. 180 ] Longitude of user's position.
lang required	string = 2 characters The lang in which to get the types localized.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"network_id": 1,
"name": "string",
"logo_url": "http://example.com",
"shape": [[10,
45
],
[-2.8,
4
],
[67,
-45.8
]
],
"center_latitude": -90,
"center_longitude": -180,
"currency": "string",
"max_simultaneous_rented_vehicle": 1,
"distance": 0,
"min_guarantee": 0,
"max_guarantee": 0,
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
}
}
]
}

Get network pricing

Return pricing (price by minute of rent, price to unlock and to free float lock) of the specified network.

path Parameters

id

required

integer >= 1

The network's identifier.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": [{"start_dow": 0,
"start_hod": "00:00:00",
"end_dow": 6,
"end_hod": "24:00:00",
"unlock_price": 0.5,
"unlock_included_time": 180,
"freefloat_lock_price": 0.75,
"use_per_minute_price": 0.15,
"on_hold_price": 0.05,
"currency": "string"
}
]
}

Offers

Get offers

Return all available offers for the nearest network.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of the user.
lng required	number [ -180 .. 180 ] Longitude of the user.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"offer_id": 1,
"title": "string",
"price": 0,
"vat_percentage": 1,
"price_w_vat": 0,
"given": 0,
"currency": "string"
}
]
}

Get payment methods for offer

Return all available payment methods usable by the user to purchase the given offer.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the offer to purchase.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string",
"instances": [{"id": 1,
"details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
}
}
]
}
],
"providers_setup_info": {"stripe": {"public_key": "string"
}
}
}

Purchase offer

Purchase an offer with the given payment method.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the offer to purchase.

Request Body schema: application/json
required

Info about what to use to purchase the offer.

payment_method_id required	integer >= 1 Identifier of the payment method to use.
user_payment_method_id	integer >= 1 Identifier of the instance of a payment method of the user. Depending on the payment method used this can be required.
discount_id	integer >= 1 Identifier of the discount to use to purchase this offer.
payment_method_parameters	object The payment method specific parameters.

Responses

Request samples

Payload

Content type

application/json

{"payment_method_id": 1,
"user_payment_method_id": 1,
"discount_id": 1,
"payment_method_parameters": { }
}

Response samples

Content type

application/json

Example

CodeSuccess

{"code": 0
}

Organizations

Get organization

Return information of user's organization.

Authorizations:

Authenticated

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"paid_outside_rules_ratio": 1,
"allow_outside_rules": true,
"logo_url": "http://example.com",
"description": "string"
}
}

Get organization rules

Return usage rules of user's organization.

Authorizations:

Authenticated

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"start_dow": 6,
"start_hod": "string",
"end_dow": 6,
"end_hod": "string",
"paid_by_org_ratio": 1,
"network_name": "string",
"network_id": 1
}
]
}

Organization pay everything for network.

Get whether or not the user's organization pay for everything for the given network.

Authorizations:

Authenticated

path Parameters

network_id

required

integer >= 1

Identifier of the network we want to check.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"organization_pay_everything_for_network": true
}
}

Get organization for enrolment

Return organization information linked to enrolment token.

query Parameters

token required	string <uuid> The enrolment token.
lang required	string^[a-z]{2}$ The language (ISO 639-1) to use for the terms of use.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": {"name": "string",
"logo_url": "http://example.com",
"description": "string",
"pay_everything": true,
"enrolment_manual_approbation": true,
"enrolment_custom_field": "string",
"terms_of_use_url": "http://example.com"
}
}

Enrol organization

Request to enrol the specified organization

Authorizations:

Authenticated

Request Body schema: application/json
required

Organization enrolment params.

token required	string <uuid> The enrolment token.
custom_field_value	string <= 500 characters Optional custom field value for organization enrolment.

Responses

Request samples

Payload

Content type

application/json

{"token": "b5507016-7da2-4777-a161-1e8042a6a377",
"custom_field_value": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Passes

Get user Passes

Return user Passes that are not used.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"duration": 7200,
"validity": "day",
"available_time": 7200,
"user_pass_id": 1,
"activation_date": "2019-08-24T14:15:22Z"
}
]
}

Enable a Pass

Activate the specified user Pass.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the user pass to activate.

Responses

Response samples

Content type

application/json

{"code": 0
}

Disable a Pass

Deactivate the specified user Pass. This can only be done if the Pass was activated less than 2 minutes ago and if the Pass was not used at all.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the user pass to deactivate.

Responses

Response samples

Content type

application/json

{"code": 0
}

Get buyable Passes

Return all available Passes to be bought for the nearest or the specified network.

Authorizations:

Authenticated

query Parameters

lat	number [ -90 .. 90 ] Latitude of the user. Required if network_id is omitted, ignored otherwise.
lng	number [ -180 .. 180 ] Longitude of the user. Required if network_id is omitted, ignored otherwise.
network_id	integer >= 1 A network identifier of which to get available Pass. If omitted, user position is required.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"duration": 7200,
"validity": "day",
"pass_id": 1,
"price": 10.4,
"currency": "string"
}
]
}

Redeem a Pass

Buy the specified Pass, paying with what is on the user's wallet.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the pass to redeem.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"user_pass_id": 1
}
}

Get payment methods for pass

Return all available payment methods usable by the user to purchase the given pass.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the pass to purchase.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string",
"instances": [{"id": 1,
"details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
}
}
]
}
],
"providers_setup_info": {"stripe": {"public_key": "string"
}
}
}

Purchase a Pass

Buy the specified Pass, paying with the chosen payment method.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the pass to purchase.

Request Body schema: application/json
required

Info about what to use to purchase the pass.

payment_method_id required	integer >= 1 Identifier of the payment method to use.
user_payment_method_id	integer >= 1 Identifier of the instance of a payment method of the user. Depending on the payment method used this can be required.
payment_method_parameters	object The payment method specific parameters.

Responses

Request samples

Payload

Content type

application/json

{"payment_method_id": 1,
"user_payment_method_id": 1,
"payment_method_parameters": { }
}

Response samples

Content type

application/json

{"code": 78,
"data": {"transaction_intent_id": 1,
"action_data": {"secureRedirectUrl": "https://some.url.com/3dsecurepage.html"
}
}
}

PaymentMethods

Get payment methods

Get the list of payment methods of the user.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string",
"instances": [{"id": 1,
"details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
}
}
],
"allow_pre_authorizations": true,
"allow_direct_payments": true,
"allow_automatic_payments": true,
"allow_subscriptions": true
}
]
}

Get available payment method

Get the list of payment method that the user can configure.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string"
}
],
"providers_setup_info": {"stripe": {"public_key": "string"
}
}
}

Configure payment method

Configure an instance of the payment method for the user.

Authorizations:

Authenticated

path Parameters

method_id

required

integer >= 1

The identifier of payment method to configure.

Request Body schema: application/json
required

Info about the bank guarantee to create.

required

object or object

Responses

Request samples

Payload

Content type

application/json

{"data": {"card_number": "string",
"expire_date": "string"
}
}

Response samples

Content type

application/json

{"code": 0,
"data": {"payment_method_setup_intent_id": 1,
"data": {"intent_id": "string",
"client_secret": "string",
"public_key": "string"
}
}
}

Get the state of a payment method setup intent

Get the current state of a payment method setup intent.

Authorizations:

Authenticated

path Parameters

intent_id

required

integer >= 1

The identifier of payment method setup intent.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": { }
}

Continue processing payment method setup intent

Continue the processing of a payment method setup intent after the user has done some actions on his side.

Authorizations:

Authenticated

path Parameters

intent_id

required

integer >= 1

The identifier of payment method setup intent.

Request Body schema: application/json
required

Info to continue the processing of a payment method setup intent.

data

required

object

Data used to process the payment method setup intent (none for now).

Responses

Request samples

Payload

Content type

application/json

{"data": { }
}

Response samples

Content type

application/json

{"code": 196
}

Delete payment method

Delete an instance of a payment method of the user.

Authorizations:

Authenticated

path Parameters

user_method_id

required

integer >= 1

The identifier of user payment method to delete.

Responses

Response samples

Content type

application/json

{"code": 0
}

Phone

Request code

Request to send a code to a phone number by SMS.

Authorizations:

PhoneValidationToken

Request Body schema: application/json
required

Info for where to send the SMS.

phone_number required	string [ 1 .. 20 ] characters ^\+\d{1,4} ?\d{3,14}$ The phone number in E.164 format to which we want to send the validation code.
lang required	string = 2 characters ^[a-zA-Z]{2}$ The language to use in the SMS, default to english if not available.

Responses

Request samples

Payload

Content type

application/json

{"phone_number": "string",
"lang": "st"
}

Response samples

Content type

application/json

{"code": 0
}

Verify a code

Verify that the user received the code previously generated and mark the phone number as verified.

Authorizations:

PhoneValidationToken

Request Body schema: application/json
required

The code received by SMS.

sms_code

required

string = 6 characters ^\d{6}$

The code received by SMS.

Responses

Request samples

Payload

Content type

application/json

{"sms_code": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"code": 0
}

Price estimation

Estimate price of a rent

Return the price for a rent of the specified time on the specified network.

Authorizations:

Authenticated

query Parameters

network_id required	integer >= 1 The identifier of the network in which the rent will be done.
start_date required	string <date-time> When the rent will start.
end_date required	string <date-time> When the rent will end.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"price": 0,
"freefloat_lock": 0,
"currency": "string"
}
}

Subscriptions

Get subscriptions

Return all available subscriptions for the nearest or the given network.

Authorizations:

Authenticated

query Parameters

lat	number [ -90 .. 90 ] Latitude of the user. Required if network_id is not provided.
lng	number [ -180 .. 180 ] Longitude of the user. Required if network_id is not provided.
network_id	integer >= 1 Network to fetch subscriptions from. Required if lat and lng are not provided.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"subscription_id": 1,
"name": "string",
"trip_duration": 1,
"trip_waiting_period": 1,
"vat_percentage": 0,
"currency": "string",
"prices": [{"subscription_price_id": 1,
"price": 0,
"interval_type": "day",
"interval_count": 1,
"free_credits": 0
}
],
"organization_discount_percent": 1,
"organization_discount_duration": "once",
"organization_discount_duration_in_months": 0
}
]
}

Get user subscriptions

Return all subscriptions of the user.

Authorizations:

Authenticated

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"user_subscription_id": 1,
"start_date": "string",
"next_renew_date": "string",
"cancellation_date": "string",
"end_date": "string",
"state": "active",
"price": 0,
"interval_type": "day",
"interval_count": 1,
"subscription_name": "string",
"trip_duration": 1,
"trip_waiting_period": 1,
"network_name": "string",
"currency": "string",
"payment_method_details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
},
"payment_method_type": "string",
"provider": "string",
"last_trip_state": "running",
"last_trip_end_date": "string",
"discount_percent": 1,
"discount_duration": "once",
"discount_duration_in_months": 0
}
]
}

Cancel subscription

Cancel a user subscription.

Authorizations:

Authenticated

path Parameters

user_subscription_id

required

integer >= 1

The identifier of the user subscription to cancel.

Responses

Response samples

Content type

application/json

{"code": 0
}

Get payment methods for user subscription

Return all available payment methods usable by the user to update the payment method used by the user subscription.

Authorizations:

Authenticated

path Parameters

user_subscription_id

required

integer >= 1

Identifier of the user subscription to update.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string",
"instances": [{"id": 1,
"details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
}
}
]
}
],
"providers_setup_info": {"stripe": {"public_key": "string"
}
}
}

Update user subscription payment method

Update the payment method used to pay for a user subscription.

Authorizations:

Authenticated

path Parameters

user_subscription_id

required

integer >= 1

The identifier of user subscription to update.

Request Body schema: application/json
required

Info to continue the processing of a payment method setup intent.

payment_method_id required	integer >= 1 Identifier of the payment method to use.
user_payment_method_id required	integer >= 1 Identifier of the instance of a payment method of the user.

Responses

Request samples

Payload

Content type

application/json

{"payment_method_id": 1,
"user_payment_method_id": 1
}

Response samples

Content type

application/json

{"code": 0
}

Confirm renew payment

Confirm the payment after 3DSecure was required for a subscription renew payment.

Authorizations:

Authenticated

path Parameters

user_subscription_id

required

integer >= 1

The identifier of user subscription to update.

Request Body schema: application/json
required

Info to confirm the payment with the payment method.

payment_method_parameters

object

The payment method specific parameters.

Responses

Request samples

Payload

Content type

application/json

{"payment_method_parameters": { }
}

Response samples

Content type

application/json

{"code": 0,
"data": {"redirect_uri": "http://example.com"
}
}

Get payment methods for subscription

Return all available payment methods usable by the user to subscribe to a subscription.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

Identifier of the subscription the user want to subscribe to.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"method_id": 1,
"type": "string",
"provider": "string",
"instances": [{"id": 1,
"details": {"alias": "XXXX XXXX XXXX 1234",
"expiration_date": "stri",
"card_provider": "mastercard"
}
}
]
}
],
"providers_setup_info": {"stripe": {"public_key": "string"
}
}
}

Subscribe

Subscribe the user to a subscription.

Authorizations:

Authenticated

path Parameters

price_id

required

integer >= 1

Identifier of the subscription price id to subscribe to.

Request Body schema: application/json
required

Info about what to use to subscribe.

payment_method_id required	integer >= 1 Identifier of the payment method to use.
user_payment_method_id required	integer or null >= 1 Identifier of the instance of a payment method of the user. Depending on the payment method used this can be required.
payment_method_parameters	object The payment method specific parameters.

Responses

Request samples

Payload

Content type

application/json

{"payment_method_id": 1,
"user_payment_method_id": 1,
"payment_method_parameters": { }
}

Response samples

Content type

application/json

Example

CodeSuccess

{"code": 0
}

Users

Begin a registration

Begin a registration by checking if the user's email match an organization.

Request Body schema: application/json
required

Email and label of the user.

email required	string <email> The user's email address.
app_label required	string The name of the application used to sign up.
lang	string/^[a-zA-Z]{2}$/ The user's language. Defaults to English.
enrolment_token	string <uuid> Optional organization enrolment token.

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"app_label": "string",
"lang": "string",
"enrolment_token": "dcfae4cf-f37b-4718-a8ef-ac19f0efd634"
}

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": {"organization": {"name": "string",
"logo_url": "http://example.com",
"description": "string",
"pay_everything": true,
"enrolment_manual_approbation": true,
"enrolment_custom_field": "string",
"terms_of_use_url": "http://example.com"
},
"sms": {"validation_token": "string"
}
}
}

Get user info

Return user's info.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": {"user_id": 1,
"email": "user@example.com",
"lastname": "string",
"firstname": "string",
"bank_card": true,
"demo_mode": true,
"trip_retention_duration": 3,
"is_knot_account": true,
"is_google_account": true,
"is_facebook_account": true,
"is_apple_account": true,
"notifications": 15,
"phone_number": "string",
"profile_picture_url": "string",
"two_factor": true,
"organization_id": 1,
"organization_name": "string",
"organization_pay_everything": true,
"organization_pay_everything_for_any_network": true,
"trip_count": 0,
"saved_payment_method_is_optional": true,
"enrolment_request_date": "2019-08-24T14:15:22Z",
"enrolment_request_organization_name": "string"
}
}

Register a user

Register a new user using an email and a password.

Request Body schema: application/json
required

Info about the user to create its account.

firstname	string [ 1 .. 50 ] characters The user's firstname.
lastname	string [ 1 .. 50 ] characters The user's lastname.
lang required	string/^[a-zA-Z]{2}$/ The user's language.
phonenumber	string/^\+\d{1,4} ?\d{3,14}$/ The user's phone number in E.164 format.
phonenumber_token	string The phone number verification token.
sponsorcode	string/^[A-Z]{8}$/ Another user's sponsor code.
	object The given consents.
app_label required	string The name of the application used to sign up.
trip_retention_in_months	integer or null [ 6 .. 24 ] The duration in months that we will keep the trips of the user. Null means forever. Will default to 24 months if not specified.
enrolment_token	string <uuid> Optional organization enrolment token.
enrolment_custom_field_value	string <= 500 characters Optional custom field value for organization enrolment.
email required	string <email> The user's email address.
password required	string [ 8 .. 255 ] characters The user's password.

Responses

Request samples

Payload

Content type

application/json

{"firstname": "string",
"lastname": "string",
"lang": "string",
"phonenumber": "string",
"phonenumber_token": "string",
"sponsorcode": "string",
"consents": {"property1": true,
"property2": true
},
"app_label": "string",
"trip_retention_in_months": 6,
"enrolment_token": "dcfae4cf-f37b-4718-a8ef-ac19f0efd634",
"enrolment_custom_field_value": "string",
"email": "user@example.com",
"password": "stringst"
}

Response samples

200
400
500

Content type

application/json

{"code": 0
}

Update user

Update the user's information.

Authorizations:

Authenticated

Request Body schema: application/json
required

User info to update.

firstname	string [ 1 .. 50 ] characters The user's firstname.
lastname	string [ 1 .. 50 ] characters The user's lastname.

Responses

Request samples

Payload

Content type

application/json

{"firstname": "string",
"lastname": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Register a user through web

Register a new user using an email and a password. This is used for registering using the web interface.

Request Body schema: application/json
required

Info about the user to create its account.

firstname	string [ 1 .. 50 ] characters The user's firstname.
lastname	string [ 1 .. 50 ] characters The user's lastname.
lang required	string/^[a-zA-Z]{2}$/ The user's language.
phonenumber	string/^\+\d{1,4} ?\d{3,14}$/ The user's phone number in E.164 format.
phonenumber_token	string The phone number verification token.
sponsorcode	string/^[A-Z]{8}$/ Another user's sponsor code.
	object The given consents.
app_label required	string The name of the application used to sign up.
trip_retention_in_months	integer or null [ 6 .. 24 ] The duration in months that we will keep the trips of the user. Null means forever. Will default to 24 months if not specified.
enrolment_token	string <uuid> Optional organization enrolment token.
enrolment_custom_field_value	string <= 500 characters Optional custom field value for organization enrolment.
email required	string <email> The user's email address.
password required	string [ 8 .. 255 ] characters The user's password.
gcaptcha required	string Google re-captcha code.

Responses

Request samples

Payload

Content type

application/json

{"firstname": "string",
"lastname": "string",
"lang": "string",
"phonenumber": "string",
"phonenumber_token": "string",
"sponsorcode": "string",
"consents": {"property1": true,
"property2": true
},
"app_label": "string",
"trip_retention_in_months": 6,
"enrolment_token": "dcfae4cf-f37b-4718-a8ef-ac19f0efd634",
"enrolment_custom_field_value": "string",
"email": "user@example.com",
"password": "stringst",
"gcaptcha": "string"
}

Response samples

200
400
500

Content type

application/json

{"code": 0
}

Register a user with Apple

Register a user using a Apple account to fetch user's information and allow login with the Apple identity provider.

Request Body schema: application/json
required

Info about the user and the data given by Apple.

lang required	string/^[a-zA-Z]{2}$/ The user's language.
phonenumber	string/^\+\d{1,4} ?\d{3,14}$/ The user's phone number in E.164 format.
phonenumber_token	string The phone number verification token.
sponsorcode	string/^[A-Z]{8}$/ Another user's sponsor code.
	object The given consents.
app_label required	string The name of the application used to sign up.
trip_retention_in_months	integer or null [ 6 .. 24 ] The duration in months that we will keep the trips of the user. Null means forever. Will default to 24 months if not specified.
enrolment_token	string <uuid> Optional organization enrolment token.
enrolment_custom_field_value	string <= 500 characters Optional custom field value for organization enrolment.
token required	string The user's Apple id token.
firstname required	string [ 1 .. 50 ] characters The user's firstname.
lastname required	string [ 1 .. 50 ] characters The user's lastname.

Responses

Request samples

Payload

Content type

application/json

{"lang": "string",
"phonenumber": "string",
"phonenumber_token": "string",
"sponsorcode": "string",
"consents": {"property1": true,
"property2": true
},
"app_label": "string",
"trip_retention_in_months": 6,
"enrolment_token": "dcfae4cf-f37b-4718-a8ef-ac19f0efd634",
"enrolment_custom_field_value": "string",
"token": "string",
"firstname": "string",
"lastname": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1
}

Link Apple

Link an account to an Apple account.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info on the Apple account to link.

token

required

string

The Apple id token.

Responses

Request samples

Payload

Content type

application/json

{"token": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Register a user with Facebook

Register a user using a Facebook account to fetch user's information and allow login with the Facebook identity provider.

Request Body schema: application/json
required

Info about the user and the data given by Facebook.

lang required	string/^[a-zA-Z]{2}$/ The user's language.
phonenumber	string/^\+\d{1,4} ?\d{3,14}$/ The user's phone number in E.164 format.
phonenumber_token	string The phone number verification token.
sponsorcode	string/^[A-Z]{8}$/ Another user's sponsor code.
	object The given consents.
app_label required	string The name of the application used to sign up.
trip_retention_in_months	integer or null [ 6 .. 24 ] The duration in months that we will keep the trips of the user. Null means forever. Will default to 24 months if not specified.
enrolment_token	string <uuid> Optional organization enrolment token.
enrolment_custom_field_value	string <= 500 characters Optional custom field value for organization enrolment.
token required	string The user's Facebook access token.
firstname required	string [ 1 .. 50 ] characters The user's firstname.
lastname required	string [ 1 .. 50 ] characters The user's lastname.

Responses

Request samples

Payload

Content type

application/json

{"lang": "string",
"phonenumber": "string",
"phonenumber_token": "string",
"sponsorcode": "string",
"consents": {"property1": true,
"property2": true
},
"app_label": "string",
"trip_retention_in_months": 6,
"enrolment_token": "dcfae4cf-f37b-4718-a8ef-ac19f0efd634",
"enrolment_custom_field_value": "string",
"token": "string",
"firstname": "string",
"lastname": "string"
}

Response samples

200
400
500

Content type

application/json

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1
}

Link Facebook

Link an account to a Facebook account.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info on the Facebook account to link.

token

required

string

The Facebook access token.

Responses

Request samples

Payload

Content type

application/json

{"token": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Register a user with Google

Register a user using a Google account to fetch user's information and allow login with the Google identity provider.

Request Body schema: application/json
required

Info about the user and the data given by Google.

lang required	string/^[a-zA-Z]{2}$/ The user's language.
phonenumber	string/^\+\d{1,4} ?\d{3,14}$/ The user's phone number in E.164 format.
phonenumber_token	string The phone number verification token.
sponsorcode	string/^[A-Z]{8}$/ Another user's sponsor code.
	object The given consents.
app_label required	string The name of the application used to sign up.
trip_retention_in_months	integer or null [ 6 .. 24 ] The duration in months that we will keep the trips of the user. Null means forever. Will default to 24 months if not specified.
enrolment_token	string <uuid> Optional organization enrolment token.
enrolment_custom_field_value	string <= 500 characters Optional custom field value for organization enrolment.
token required	string The user's Google access token.
firstname required	string [ 1 .. 50 ] characters The user's firstname.
lastname required	string [ 1 .. 50 ] characters The user's lastname.

Responses

Request samples

Payload

Content type

application/json

{"lang": "string",
"phonenumber": "string",
"phonenumber_token": "string",
"sponsorcode": "string",
"consents": {"property1": true,
"property2": true
},
"app_label": "string",
"trip_retention_in_months": 6,
"enrolment_token": "dcfae4cf-f37b-4718-a8ef-ac19f0efd634",
"enrolment_custom_field_value": "string",
"token": "string",
"firstname": "string",
"lastname": "string"
}

Response samples

200
400
500

Content type

application/json

{"code": 0,
"token": "string",
"refresh_token": "string",
"user_id": 1
}

Link Google

Link an account to a Google account.

Authorizations:

Authenticated

Request Body schema: application/json
required

Info on the Google account to link.

token

required

string

The Google access token.

Responses

Request samples

Payload

Content type

application/json

{"token": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Update user's notifications

Update the user's notifications settings.

Authorizations:

Authenticated

Request Body schema: application/json
required

Notification settings.

value

required

number [ 0 .. 15 ]

Value of the settings. Flags: 1 -> Deprecated, 2 -> Deprecated, 4 -> service status, 8 -> trip notifications.

Responses

Request samples

Payload

Content type

application/json

{"value": 15
}

Response samples

Content type

application/json

{"code": 0
}

Delete a user

Delete a user and all its personal data.

Authorizations:

Authenticated

Request Body schema: application/json
required

Deletion data.

password

string [ 8 .. 255 ] characters

The user's password, required when the user has one.

Responses

Request samples

Payload

Content type

application/json

{"password": "stringst"
}

Response samples

200
400
402
403
500

Content type

application/json

{"code": 0,
"data": {"days": 1
}
}

Cancel deletion

Cancel the deletion of a user while in the pending deletion period.

Authorizations:

Authenticated

Request Body schema: application/json
required

Cancel deletion data.

cancel_token

required

string

The token given by a route that returned that the account is pending deletion.

Responses

Request samples

Payload

Content type

application/json

{"cancel_token": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"code": 0
}

Demonstration mode

Change the account demonstration mode state.

Authorizations:

Authenticated

Request Body schema: application/json
required

New state of the demonstration mode.

activate

required

boolean

The state of the demonstration mode.

Responses

Request samples

Payload

Content type

application/json

{"activate": true
}

Response samples

Content type

application/json

{"code": 0
}

Add password

Add a password to a Google, Facebook or Apple account.

Authorizations:

Authenticated

Request Body schema: application/json
required

New password.

password

required

string [ 8 .. 255 ] characters

The user's password.

Responses

Request samples

Payload

Content type

application/json

{"password": "stringst"
}

Response samples

Content type

application/json

{"code": 0
}

Change password

Change the user's password.

Authorizations:

Authenticated

Request Body schema: application/json
required

New and old password.

password required	string [ 8 .. 255 ] characters The user's old password.
newpassword required	string [ 8 .. 255 ] characters The user's new password.

Responses

Request samples

Payload

Content type

application/json

{"password": "stringst",
"newpassword": "stringst"
}

Response samples

Content type

application/json

{"code": 0
}

Reset password

Reset the password to the new specified one.

Request Body schema: application/json
required

The new password.

password_token required	string = 10 characters The change password token.
password required	string [ 8 .. 255 ] characters The user's password.

Responses

Request samples

Payload

Content type

application/json

{"password_token": "stringstri",
"password": "stringst"
}

Response samples

200
400
401
410
500

Content type

application/json

{"code": 0
}

Get basic personal data

Return user's basic personal data.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": {"firstname": "string",
"lastname": "string",
"user_id": 1,
"email": "user@example.com",
"language": "st",
"notifications": 15,
"offers_bought": 0,
"phone_number": "string",
"google_id": "string",
"facebook_id": "string",
"apple_id": "string",
"organization_id": 1,
"app_label_id": 1,
"use_time": {"seconds": 0,
"minutes": 0,
"hours": 0,
"days": 0
}
}
}

Request full personal data

Request all user's personal data to be sent by email.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0
}

Update user's profile picture

Upload a profile picture to the specified user.

Authorizations:

Authenticated

Request Body schema: multipart/form-data
required

The image to upload.

profile_picture

required

string <binary>

The picture to upload.

Responses

Response samples

Content type

application/json

{"code": 0
}

Push notifications

Update the push notification token.

Authorizations:

Authenticated

Request Body schema: application/json
required

New push notification token.

token required	string <= 4096 characters The push notification token.
device_id required	string <= 50 characters Identifier of the device being used.

Responses

Request samples

Payload

Content type

application/json

{"token": "string",
"device_id": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Get user rents

Return user's ongoing rents.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"vehicle_id": 1,
"serial_number": "string",
"free_floating": true,
"being_rented": true,
"displayed_number": 1,
"lock_status": 0,
"trip_id": 1,
"time_start": "2019-08-24T14:15:22Z",
"billing_time_stop": "2019-08-24T14:15:22Z",
"on_hold_since": "2019-08-24T14:15:22Z",
"on_hold_activated": true,
"network_id": 1,
"battery_level": 100,
"min_battery_to_slow_down": 100,
"min_battery_to_auto_lock": 100,
"avg_max_range": 0,
"external_locks": [{"external_lock_id": 1,
"model": "string",
"type": "u",
"code": "string"
}
]
}
],
"passes": [{"pass_id": 1,
"end_date": "2019-08-24T14:15:22Z",
"in_use": true
}
]
}

Get user's wallet amount

Return the sum of user's wallets.

Authorizations:

Authenticated

query Parameters

currency

required

string (Currency)

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BRL" "BSD" "BTN" "BWP" "BYN" "BYR" "BZD" "CAD" "CDF" "CHF" "CLF" "CLP" "CNY" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "IMP" "INR" "IQD" "IRR" "ISK" "JEP" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XCD" "XDR" "XOF" "XPF" "YER" "ZAR" "ZMK" "ZMW" "ZWL"

Example: currency=EUR

The requested currency, in which the sum should be converted.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"amount": 0
}
}

Update phone number

Update the user's phone number or, when required, send a verification code by SMS and return a token to validate the ownership of the number.

Authorizations:

Authenticated

Request Body schema: application/json
required

The new phone number.

phone_number required	string [ 1 .. 20 ] characters ^\+\d{1,4} ?\d{3,14}$ The new phone number in E.164 format of the user.
lang required	string = 2 characters ^[a-zA-Z]{2}$ The language to use in the SMS, default to english if not available.

Responses

Request samples

Payload

Content type

application/json

{"phone_number": "string",
"lang": "st"
}

Response samples

Content type

application/json

Example

CodeSuccess

{"code": 0
}

End phone number update

End a phone number update that needed a validation by sms.

Authorizations:

Authenticated

Request Body schema: application/json
required

The token given by the POST route and code received by SMS.

sms_code required	string = 6 characters ^\d{6}$ The 6 digit code received by SMS.
token required	string The token given by the POST route.

Responses

Request samples

Payload

Content type

application/json

{"sms_code": "string",
"token": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Update trip retention

Change the duration for when the trips are kept linked to the requesting user.

Authorizations:

Authenticated

Request Body schema: application/json
required

The new trip retention duration.

months

required

integer or null [ 6 .. 24 ]

The number of months to keep the trip linked to the user. null means forever.

Responses

Request samples

Payload

Content type

application/json

{"months": 6
}

Response samples

Content type

application/json

{"code": 0
}

Reports

Create an app report

Create a new report of type app, called by the app when it receive an error code from the backend, used to store it.

Authorizations:

Authenticated

Request Body schema: application/json
required

Application report data.

code required	integer The error code returned by the backend.
app_page required	string [ 1 .. 128 ] characters Identifier of the application's page that received the error.
app_version required	string [ 1 .. 32 ] characters Version of the application that received the error.
device_os required	string [ 1 .. 32 ] characters Operating system of the device that run the app.
device	string [ 1 .. 128 ] characters Name of the device that run the app.
app_label	string [ 1 .. 20 ] characters The white label of the app.

Responses

Request samples

Payload

Content type

application/json

{"code": 0,
"app_page": "string",
"app_version": "string",
"device_os": "string",
"device": "string",
"app_label": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Create an anonymous app report

Create a new report of type app, called by the app when it receive an error code from the backend, used to store it. Do not require authentication.

Authorizations:

Authenticated

Request Body schema: application/json
required

Anonymous application report data.

code required	integer The error code returned by the backend.
app_page required	string [ 1 .. 128 ] characters Identifier of the application's page that received the error.
app_version required	string [ 1 .. 32 ] characters Version of the application that received the error.
device_os required	string [ 1 .. 32 ] characters Operating system of the device that run the app.
device	string [ 1 .. 128 ] characters Name of the device that run the app.
app_label	string [ 1 .. 20 ] characters The white label of the app.

Responses

Request samples

Payload

Content type

application/json

{"code": 0,
"app_page": "string",
"app_version": "string",
"device_os": "string",
"device": "string",
"app_label": "string"
}

Response samples

200
400
500

Content type

application/json

{"code": 0
}

Create vehicle report

Create a new damaged vehicle report with a picture.

Authorizations:

Authenticated

Request Body schema: multipart/form-data
required

The picture to upload & some info for the report.

report_photo required	string <binary> The picture file data.
user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
vehicle_lat required	number [ -90 .. 90 ] Latitude of the vehicle given by the user.
vehicle_lng required	number [ -180 .. 180 ] Longitude of the vehicle given by the user.
comment required	string A text explaining what is happening.
serial_number	string^[a-zA-Z0-9]{6,10}$ The serial number of the vehicle.

Responses

Response samples

Content type

application/json

{"code": 0
}

Create vehicle report

Create a new damaged vehicle report without a picture.

Authorizations:

Authenticated

Request Body schema: application/json
required

Some info for the report.

user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
vehicle_lat required	number [ -90 .. 90 ] Latitude of the vehicle given by the user.
vehicle_lng required	number [ -180 .. 180 ] Longitude of the vehicle given by the user.
comment required	string A text explaining what is happening.
serial_number	string^[a-zA-Z0-9]{6,10}$ The serial number of the vehicle.

Responses

Request samples

Payload

Content type

application/json

{"user_lat": -90,
"user_lng": -180,
"vehicle_lat": -90,
"vehicle_lng": -180,
"comment": "string",
"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Create station full report

Create a new station full report.

Authorizations:

Authenticated

Request Body schema: application/json
required

Some info for the report.

user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
cluster_id required	integer >= 1 The identifier of the damaged cluster.
serial_number	string^[a-zA-Z0-9]{6,10}$ The serial number of the vehicle the user is trying to park.

Responses

Request samples

Payload

Content type

application/json

{"user_lat": -90,
"user_lng": -180,
"cluster_id": 1,
"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0,
"data": {"can_park_outside": true
}
}

Create station report

Create a new damaged station report with a picture.

Authorizations:

Authenticated

Request Body schema: multipart/form-data
required

The picture to upload & some info for the report.

report_photo required	string <binary> The picture file data.
user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
comment required	string A text explaining what is happening.
spots	Array of integers[ items >= 1 ] A list of spot damaged.
cluster_id required	integer >= 1 The identifier of the damaged cluster.

Responses

Response samples

Content type

application/json

{"code": 0
}

Create station report

Create a new damaged station report without a picture.

Authorizations:

Authenticated

Request Body schema: application/json
required

Some info for the report.

user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
comment required	string A text explaining what is happening.
spots	Array of integers[ items >= 1 ] A list of spot damaged.
cluster_id required	integer >= 1 The identifier of the damaged cluster.

Responses

Request samples

Payload

Content type

application/json

{"user_lat": -90,
"user_lng": -180,
"comment": "string",
"spots": [1
],
"cluster_id": 1
}

Response samples

Content type

application/json

{"code": 0
}

Create text report

Create a new text report with a picture.

Authorizations:

Authenticated

Request Body schema: multipart/form-data
required

The picture to upload & some info for the report.

report_photo required	string <binary> The picture file data.
user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
comment required	string A text explaining what is happening.

Responses

Response samples

Content type

application/json

{"code": 0
}

Create text report

Create a new text report without a picture.

Authorizations:

Authenticated

Request Body schema: application/json
required

Some info for the report.

user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
comment required	string A text explaining what is happening.

Responses

Request samples

Payload

Content type

application/json

{"user_lat": -90,
"user_lng": -180,
"comment": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Create payment report

Create a new report about a payment issue.

Authorizations:

Authenticated

Request Body schema: application/json
required

Some info for the report.

user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
comment required	string A text explaining what is happening.

Responses

Request samples

Payload

Content type

application/json

{"user_lat": -90,
"user_lng": -180,
"comment": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Create trip not ending report

Trip not ending designate the case when the user returned the vehicle but the end of the trip was not detected. Calling this route without a comment will try to auto remediate the problem, if it's possible it will automatically create the report. In case of failure to auto remediate, you need to call this route with a comment to just create the report.

Authorizations:

Authenticated

Request Body schema: application/json
required

Some info for the report.

user_lat required	number [ -90 .. 90 ] Latitude of the user making the report.
user_lng required	number [ -180 .. 180 ] Longitude of the user making the report.
comment	string A text explaining what is happening. When not given, the route will try to automatically solve the problem.
cluster_id required	integer >= 1 The identifier of the cluster in which the vehicle was put.
serial_number required	string^[a-zA-Z0-9]{6,10}$ The serial number of the vehicle the user locked but its trip did not end.
spot_id required	integer >= 1 The identifier of the spot in which the vehicle was put.

Responses

Request samples

Payload

Content type

application/json

{"user_lat": -90,
"user_lng": -180,
"comment": "string",
"cluster_id": 1,
"serial_number": "string",
"spot_id": 1
}

Response samples

Content type

application/json

{"code": 0,
"data": {"auto_remediation": true,
"billing_time_stop": "2019-08-24T14:15:22Z"
}
}

Stocks

Get stocks addresses

Return all addresses where vehicles can be stored.

Authorizations:

(AuthenticatedPermissions)

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"stock_id": 1,
"name": "string",
"country": "string",
"country_id": 1,
"city": "string",
"zipcode": "string",
"street": "string"
}
]
}

Move a vehicle to stock

Move a vehicle from missing vehicles to an existing stock.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

The vehicle and the identifier of the stock to put in.

serial_number required	string/^[a-zA-Z0-9]{6,10}$/ The serial number of the vehicle to move.
stock required	integer >= 1 The identifier of the stock in which we move the vehicle.
comment	string [ 1 .. 2048 ] characters A comment on why we moved the vehicle to a stock.

Responses

Request samples

Payload

Content type

application/json

{"serial_number": "SXB003",
"stock": 1,
"comment": "I put this vehicle in stock with an example comment"
}

Response samples

Content type

application/json

{"code": 0
}

Vehicles

Admin unlock vehicle

Unlock the specified vehicle in admin mode.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Vehicle unlock parameters.

lat required	number [ -90 .. 90 ] Latitude of the user to check the distance to the vehicle.
lng required	number [ -180 .. 180 ] Longitude of the user to check the distance to the vehicle.
serial_number required	string/^[a-zA-Z0-9]{6,10}$/ The serial number of the vehicle to unlock.
force	boolean True when the distance check is bypassed.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180,
"serial_number": "string",
"force": true
}

Response samples

Content type

application/json

{"code": 0
}

Get free floating vehicles

Return all free floating vehicles in a given area.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get free floating vehicles.
lng required	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get free floating vehicles.
latDeg required	number >= 0 Number of latitude degree of the area of which we want to get free floating vehicles.
lngDeg required	number >= 0 Number of longitude degree of the area of which we want to get free floating vehicles.
lang	string = 2 characters Language in which to get the localization, defaults to 'en'.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"vehicle_id": 1,
"serial_number": "string",
"latitude": -90,
"longitude": -180,
"connected": true,
"network_id": 1,
"battery_level": 100,
"vehicle_type": "kick-scooter",
"state": "rented",
"is_accessible": true,
"is_available": true,
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"has_freefloat_to_station_reward": true
}
]
}

Freefloat lock

Lock in free floating the specified vehicle and ends the rent.

Authorizations:

Authenticated

Request Body schema: application/json
required

Vehicle lock parameters.

vehicle_id required	integer >= 1 The vehicle's identifier.
force	boolean When true, if the network force lock is in manual mode and the vehicle fails to lock because it produces an error, we will try to lock the vehicle as soon as possible.

Responses

Request samples

Payload

Content type

application/json

{"vehicle_id": 1,
"force": true
}

Response samples

Content type

application/json

{"code": 0
}

Admin freefloat lock

Lock in free floating the specified vehicle in admin.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Vehicle lock parameters.

serial_number required	string/^[a-zA-Z0-9]{6,10}$/ The serial number of the vehicle to lock.
force	boolean When true, if the network force lock is in manual mode and the vehicle fails to lock due to it moving, we will try to lock the vehicle as soon as possible.

Responses

Request samples

Payload

Content type

application/json

{"serial_number": "string",
"force": true
}

Response samples

Content type

application/json

{"code": 0
}

Temporary lock free floating vehicle

Temporary lock a free-floating vehicle, put the trip on hold.

Authorizations:

Authenticated

Request Body schema: application/json
required

Vehicle lock params.

vehicle_id required	integer >= 1 The vehicle's identifier.
force	boolean When true, if the network force lock is in manual mode and the vehicle fails to lock because it produces an error, we will try to lock the vehicle as soon as possible.

Responses

Request samples

Payload

Content type

application/json

{"vehicle_id": 1,
"force": true
}

Response samples

Content type

application/json

{"code": 0
}

Get a freefloat to station reward

Return the reward that the user can have if it returns the vehicle to a station.

Authorizations:

Authenticated

path Parameters

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The vehicle's serial number.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"cluster_id": 0,
"cluster_name": "string",
"currency": "EUR",
"distance_reward": 0,
"free_credits": 0
}
}

Identify free floating vehicles

Identify a free-floating vehicle by blinking it's light and emitting a sound.

Authorizations:

Authenticated

Request Body schema: application/json
required

Vehicle identify parameters.

lat required	number [ -90 .. 90 ] Latitude of the user to check the distance to the vehicle.
lng required	number [ -180 .. 180 ] Longitude of the user to check the distance to the vehicle.
serial_number required	string/^[a-zA-Z0-9]{6,10}$/ The serial number of the vehicle to unlock.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180,
"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Identify free floating vehicles as admin

Identify a free-floating vehicle by blinking it's light and emitting a sound.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Vehicle identify parameters.

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The serial number of the vehicle.

Responses

Request samples

Payload

Content type

application/json

{"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Get public free floating vehicles

Return all free floating vehicles in the given area visible without being logged in.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get free floating vehicles.
lng required	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get free floating vehicles.
latDeg required	number >= 0 Number of latitude degree of the area of which we want to get free floating vehicles.
lngDeg required	number >= 0 Number of longitude degree of the area of which we want to get free floating vehicles.
network_id	integer >= 1 Network id to filter free floating vehicles.
app_label	string non-empty Name of the app label making the request.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": [{"vehicle_id": 1,
"serial_number": "string",
"latitude": -90,
"longitude": -180,
"connected": true,
"network_id": 1,
"battery_level": 100,
"vehicle_type": "kick-scooter"
}
]
}

Get a free floating vehicle

Return a free floating vehicle.

Authorizations:

Authenticated

path Parameters

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The vehicle's serial number.

query Parameters

lang	string = 2 characters Language in which to get the localization, defaults to 'en'.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"vehicle_id": 1,
"serial_number": "string",
"latitude": -90,
"longitude": -180,
"connected": true,
"network_id": 1,
"battery_level": 100,
"vehicle_type": "kick-scooter",
"state": "rented",
"is_accessible": true,
"is_available": true,
"exceptional_out_of_order": {"exceptional_out_of_order_id": 1,
"type": "other",
"reason": "string",
"custom_reason": "string"
},
"has_freefloat_to_station_reward": true
}
}

Shutdown vehicle

Shutdown the vehicle and the IoT (e.g. for transport).

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Vehicle shutdown parameters.

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The serial number of the vehicle.

Responses

Request samples

Payload

Content type

application/json

{"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Request a vehicle

Experimental PoC: Request a vehicle to come at user position.

Authorizations:

Authenticated

Request Body schema: application/json
required

Vehicle request parameters.

lat required	number [ -90 .. 90 ] Latitude of the center of the area of which we want to get free floating vehicles.
lng required	number [ -180 .. 180 ] Longitude of the center of the area of which we want to get free floating vehicles.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180
}

Response samples

Content type

application/json

{"code": 0,
"data": {"report_id": 1
}
}

Get vehicles models

Return all currently used vehicles models.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"model_id": 1,
"manufacturer": "string",
"model_name": "string",
"model_type": "kick-scooter"
}
]
}

Get nearest parking

Return nearest clusters and parking where the given vehicle can be parked.

Authorizations:

Authenticated

query Parameters

lat required	number [ -90 .. 90 ] The latitude of where the user is.
lng required	number [ -180 .. 180 ] The longitude of where the user is.
vehicle_id required	integer >= 1 The identifier of the vehicle we want to park.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"clusters": [{"latitude": 48.5900027,
"longitude": 7.7531998,
"distance": 0,
"cluster_id": 1
}
],
"parkings": [{"latitude": 48.5900027,
"longitude": 7.7531998,
"distance": 0,
"virtual_parking_id": 1
}
]
}
}

Vehicle info

Fetch some info on the vehicle.

Authorizations:

Authenticated

path Parameters

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The vehicle's serial number.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"vehicle_id": 1,
"network_id": 1,
"battery_level": 100,
"svaas_id": 1,
"network_name": "string",
"connected": true,
"vehicle_type": "kick-scooter"
}
}

Vehicle admin info

Fetch some admin info on the vehicle. This is reserved for operators.

Authorizations:

(AuthenticatedPermissions)

path Parameters

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The vehicle's serial number.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"vehicle_id": 1,
"network_id": 1,
"battery_level": 100,
"svaas_id": 1,
"network_name": "string",
"connected": true,
"vehicle_type": "kick-scooter",
"external_locks": [{"external_lock_id": 0,
"model": "string",
"type": "u",
"serial_number": "string",
"code": "string",
"register_date": "string",
"last_code_update": "string"
}
]
}
}

Vehicle admin info refreshed

Fetch some admin info on the vehicle after getting it from the vehicle itself. This is reserved for operators.

Authorizations:

(AuthenticatedPermissions)

path Parameters

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The vehicle's serial number.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"vehicle_id": 1,
"network_id": 1,
"battery_level": 100,
"svaas_id": 1,
"network_name": "string",
"connected": true,
"vehicle_type": "kick-scooter",
"external_locks": [{"external_lock_id": 0,
"model": "string",
"type": "u",
"serial_number": "string",
"code": "string",
"register_date": "string",
"last_code_update": "string"
}
]
}
}

Change network

Change the current network of a vehicle.

Authorizations:

(AuthenticatedPermissions)

path Parameters

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The vehicle's serial number.

Request Body schema: application/json
required

Info about the network.

network_id

required

integer >= 1

Identifier of the new network for the vehicle.

Responses

Request samples

Payload

Content type

application/json

{"network_id": 1
}

Response samples

Content type

application/json

{"code": 0
}

Open battery cover

Send command for open the vehicle battery cover.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Vehicle open battery cover parameters.

serial_number

required

string/^[a-zA-Z0-9]{6,10}$/

The serial number of the vehicle.

Responses

Request samples

Payload

Content type

application/json

{"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0
}

Unlock

Unlock the specified vehicle if the user is close enough.

Authorizations:

Authenticated

Request Body schema: application/json
required

Vehicle unlock parameters.

lat required	number [ -90 .. 90 ] Latitude of the user to check the distance to the vehicle.
lng required	number [ -180 .. 180 ] Longitude of the user to check the distance to the vehicle.
serial_number required	string/^[a-zA-Z0-9]{6,10}$/ The serial number of the vehicle to unlock.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180,
"serial_number": "string"
}

Response samples

Content type

application/json

{"code": 0,
"data": {"external_locks": [{"external_lock_id": 1,
"model": "string",
"type": "u",
"code": "string"
}
]
}
}

Sponsorship

Get sponsorship

Return sponsorship info.

Authorizations:

Authenticated

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"url": "string",
"spcode": "stringst",
"currency": "string",
"sponsoring_reward": 0,
"sponsored_reward": 0
}

Spots

Get all information about a spot

Return all information about a spot.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The spot's identifier.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"spot_id": 1,
"contained_vehicle_id": 1,
"station_id": 1,
"displayed_number": 1,
"in_maintenance": true,
"lock_status": 0,
"vehicle_accessible": true,
"battery_level": 0,
"avg_max_range": 0,
"serial_number": "string"
}
}

Edit displayed number

Edit the displayed number of a spot.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

New displayed number for this spot.

spot_id required	integer >= 1 The spot's identifier.
displayed_number required	integer >= 1 The displayed number of the spot.

Responses

Request samples

Payload

Content type

application/json

{"spot_id": 1,
"displayed_number": 1
}

Response samples

Content type

application/json

{"code": 0
}

Unlock

Unlock the specified spot if the user is close enough.

Authorizations:

Authenticated

Request Body schema: application/json
required

Spot unlock parameters.

lat required	number [ -90 .. 90 ] Latitude of the user to check that it is not too far away to unlock.
lng required	number [ -180 .. 180 ] Longitude of the user to check that it is not too far away to unlock.
cluster_id required	integer >= 1 The identifier of the cluster on which the spot is located.
displayed_number required	integer >= 1 The number displayed on the spot.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180,
"cluster_id": 1,
"displayed_number": 1
}

Response samples

Content type

application/json

{"code": 0,
"data": {"external_locks": [{"external_lock_id": 1,
"model": "string",
"type": "u",
"code": "string"
}
]
}
}

Admin unlock

Unlock the specified spot in admin mode.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Spot unlock parameters.

lat required	number [ -90 .. 90 ] Latitude of the user to check that it is not too far away to unlock.
lng required	number [ -180 .. 180 ] Longitude of the user to check that it is not too far away to unlock.
spot_id required	integer >= 1 The identifier of the spot to be unlocked.
force	boolean True when the unlocking is confirmed despite the distance.

Responses

Request samples

Payload

Content type

application/json

{"lat": -90,
"lng": -180,
"spot_id": 1,
"force": true
}

Response samples

Content type

application/json

{"code": 0
}

Stations

Create a station

Create a new station with belonging spots on the given cluster.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Station create parameters.

station_id required	integer >= 1 The SVaaS station identifier.
cluster_id required	integer >= 1 The cluster's identifier.

Responses

Request samples

Payload

Content type

application/json

{"station_id": 1,
"cluster_id": 1
}

Response samples

Content type

application/json

{"code": 0
}

Set station volume

Changes the speaker's volume of the specified station.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Station volume parameters.

station_id required	integer >= 1 The station's identifier.
volume required	integer [ 1 .. 100 ] The new volume in percentage.

Responses

Request samples

Payload

Content type

application/json

{"station_id": 1,
"volume": 1
}

Response samples

Content type

application/json

{"code": 0
}

Set station alarm threshold

Changes the alarm threshold of the specified station.

Authorizations:

(AuthenticatedPermissions)

Request Body schema: application/json
required

Station alarm threshold parameters.

station_id required	integer >= 1 The station's identifier.
threshold required	integer [ 1 .. 100 ] The new alarm threshold in percentage.

Responses

Request samples

Payload

Content type

application/json

{"station_id": 1,
"threshold": 1
}

Response samples

Content type

application/json

{"code": 0
}

Get stations of a cluster

Return all station's of the specified cluster with some information.

Authorizations:

(AuthenticatedPermissions)

path Parameters

id

required

integer >= 1

The identifier of the cluster of which we want to get it's stations.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"station_id": 1,
"min_displayed_number": 1,
"max_displayed_number": 1,
"speaker_volume": 100,
"alarm_threshold": 100
}
]
}

TermsOfUse

Check ToU content

Get content of the specified terms of use.

query Parameters

lang	string = 2 characters The preferred lang of the terms of use to get.
app_label	string <= 20 characters The name of the application white label calling the route. Default to knot.
token	string <= 20 characters Terms of use acceptation token. Use it to show terms of use associated to an approval request.
term_of_use_id	number >= 1 Identifier of the terms of use to get content.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": {"content": "string",
"publication_url": "http://example.com",
"file_name": "string"
}
}

Get ToU url

Get the url to the latest terms of use.

Authorizations:

Authenticated

query Parameters

lang	string = 2 characters The preferred lang of the terms of use to get.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"app_label_url": "http://example.com",
"network_url": "http://example.com",
"organization_url": "http://example.com"
}
}

Check ToU acceptation

Check that the user accepted the latest terms of use.

Authorizations:

Authenticated

query Parameters

lang	string = 2 characters The preferred lang of the terms of use to get.

Responses

Response samples

Content type

application/json

{"code": 0
}

Accept ToU

Accept the specified terms of use.

Authorizations:

TermsOfUseValidationToken

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0
}

Transactions

Get transactions

Returns all transactions of the user.

Authorizations:

Authenticated

query Parameters

last_trip_id	integer >= 1 The identifier of the last trip we have, to get the trip coming after it.
direction	string Enum: "ASC" "DESC" The direction in which to sort the trips.
items	integer [ 1 .. 100 ] The number of items to return, default to 100 for compatibility.

Responses

Response samples

200
401
403
410
500

Content type

application/json

{"code": 0,
"data": [{"transaction_id": 1,
"date": "2019-08-24T14:15:22Z",
"auto_payment": true,
"amount": 0,
"vat": 1,
"amount_w_vat": 0,
"currency": "string",
"wallet_amount": 0,
"offer_id": 1,
"discount": 0,
"offer_wallet_amount": "string",
"pass_id": 1,
"pass_duration": 0,
"pass_validity": "day",
"user_subscription_id": 1,
"refunds": [{"id": 1,
"amount": 0,
"date": "string"
}
],
"trip_id": 1,
"trip_cost": 0,
"trip_started_at": "string"
}
]
}

Get invoice

Returns the invoice for a transaction.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The transaction's identifier.

Responses

Response samples

401
403
404
410
500

Content type

application/json

Example

CodeAccessTokenInvalid

{"code": 3
}

Sending invoice by mail

Sending the invoice for a transaction by mail.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The transaction's identifier.

Responses

Response samples

Content type

application/json

{"code": 0
}

TransactionsIntents

Get the state of a transaction intent

Get the current state of a transaction intent.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the transaction intent.

Responses

Response samples

Content type

application/json

{"code": 196
}

Continue processing transaction intent

Continue the processing of a transaction intent after the user has done some actions on his side.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the transaction intent.

Responses

Response samples

Content type

application/json

{"code": 196
}

Trips

Get trips

Returns all trips made by the user.

Authorizations:

Authenticated

query Parameters

last_trip_id	integer >= 1 The identifier of the last trip we have, to get the trip coming after it.
direction	string Enum: "ASC" "DESC" The direction in which to sort the trips.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": [{"trip_id": 1,
"billing_time_stop": "2019-08-24T14:15:22Z",
"distance": 0,
"url_picture": "http://example.com",
"start_date": "string",
"has_balancing_discount": true
}
]
}

Get a trip

Returns a trip made by the user.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the trip we want to get.

Responses

Response samples

Content type

application/json

{"code": 0,
"data": {"trip_id": 1,
"billing_time_stop": "2019-08-24T14:15:22Z",
"distance": 0,
"coords": [{"lat": -90,
"lng": -180,
"date": "2019-08-24T14:15:22Z"
}
],
"on_hold_time": 0,
"trip_cost": 0,
"currency": "string",
"paid_with_pass": true,
"balancing_discount": 0
}
}

Hide a trip

Hide a trip made by the user.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the trip we want to hide.

Responses

Response samples

Content type

application/json

{"code": 0
}

Resume a trip

Resume a trip that was put on-hold previously, unlock the vehicle.

Authorizations:

Authenticated

path Parameters

id

required

integer >= 1

The identifier of the trip to resume.

Responses

Response samples

Content type

application/json

{"code": 0
}

Versions

Get app versions

Get the latest and minimal application's version.

query Parameters

app_label required	string [ 1 .. 20 ] characters The app label name.
platform required	string Enum: "android" "ios" The platform name.

Responses

Response samples

200
400
500

Content type

application/json

{"code": 0,
"data": {"current": 0,
"minimal": 0
}
}

Mobile application API definition (1.0.0)

AppLabel

Get app download url

query Parameters

Responses

Response samples

Badges

Get user's badges

Authorizations:

Responses

Response samples

Link badge

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update name

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete a badge

Authorizations:

query Parameters

Responses

Response samples

BankGuarantees

Get user bank guarantees

Authorizations:

Responses

Response samples

Create user bank guarantee

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get payment methods for bank guarantee

Authorizations:

query Parameters

Responses

Response samples

Cancel bank guarantee

Authorizations:

path Parameters

Responses

Response samples

Chats

Get chat channels

Authorizations:

Responses

Response samples

Get a chat channel

Authorizations:

path Parameters

Responses

Response samples

Upload image

Authorizations:

path Parameters

Request Body schema: multipart/form-datarequired

Responses

Response samples

Clusters

Get clusters

Authorizations:

query Parameters

Responses

Response samples

Create cluster

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get public clusters

query Parameters

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: multipart/form-data
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required