API docs by Redocly

Urban Sharing - MAAS API (1.6.0)

Download OpenAPI specification:

Urban Sharing Support: info@urbansharing.com URL: https://www.urbansharing.com

The MAAS (Mobility as a Service) API enables third party access to Urban Sharing mobility functionality. The API provides access to the following services:

  • Initiating vehicle trips using a vehicle ID, QR code, or station ID.
  • Trip status event stream – each time the status of a trip changes, an event will be sent to your webhook.
  • Retrieving trip state information.
  • Updating an ongoing trip state – pause, resume, cancel, or end.
  • Damage reporting, including creating damage reports and requesting damage types.
  • Vehicle damage reporting.
  • Vehicle reservation, including creating and canceling reservations.
  • Retrieving product details.
  • Managing penalties, including finding, adding, and resolving user penalties.

The Urban Sharing Maas API does not provide the following features. These features need to be managed by the client:

  • User Management
  • Product Management
  • Payment
  • Apps

If these are features you require you may be interested in the Urban Sharing Fleet management product. Please contact Urban Sharing for more information.

To receive events you can implement a number of webhooks.

  • /trips/events - Posts the status of a trip when it changes
  • /reservations - Posts the status of a reservation when it changes
  • /users/invoices - Posts an invoice when a trip with a product ID ends
  • /users/penalties - Posts an update when a user incurs penalty points. Only applicable to trips started with a product ID
  • /users/messages - Posts messages destined for a user

Release History
DateVersionNotes
Fri Feb 06 20261.6.0Add maxSpeedKmh to create trip endpoints
Add centroid to areas
Add all systems endpoint
Add system endpoint
Fri Mar 28 20251.5.1Add additional documentation in Getting Started
Mon Jun 10 20241.5.0Add dockGroupName to locations
Wed Feb 14 20241.4.0Add vehicles/:id endpoint
Add lastTripId to vehicle
Implement TripStateTransitionReason
Mon Jan 22 20241.3.0Add "productId" to create reservation endpoints
Remove "maas/" prefix from all webhooks
Rename "vehicle QR" code and "GBFS ID" endpoints
Improve descriptions in documentation
Mon Oct 30 20231.2.0Add "productId" to create trip endpoints
Mon Oct 16 20231.1.0Add "products" endpoint
Thu Aug 10 20231.0.1Move vehicles/:vehicleId/damagereports/types results to row property
Tue Aug 08 20231.0.0Initial release

Authentication

To use this API you must first obtain API credentials from Urban Sharing. These API credentials can then be used to generate a JWT token which must be passed in the Authorization header when accessing resources in this API.

For more information, please refer to the Urban Sharing Auth API


Webhook Authentication

Urban Sharing generates webhook signatures using a hash-based message authentication code (HMAC) with SHA-256. You can validate the signature of the request body as follows:

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v0 corresponds to the signature.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating: The timestamp (as a string) The character . The actual JSON payload - the body of the request

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use client secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Signature Validation Example

Here is an example of how to validate a webhook signature in Typescript. 
validateWebhookSignature(
  clientSecret: string,
  signature: string,
  data: unknown,
  maxAgeMs = 5000,
): boolean {
  const [timestampPair, ...signatures] = signature.split(',');

  const timestamp = +timestampPair.split('=')[1];

  // Check that the timestamp is not too old
  if (maxAgeMs > 0) {
    const latestTimestamp = new Date().getTime() - maxAgeMs;

    if (timestamp < latestTimestamp) {
      return false;
    }
  }

  // Convert signatures into an object
  const signatureObject: any = signatures.reduce((acc, curr) => {
    const [key, value] = curr.split('=');
    acc[key] = value;
    return acc;
  }, {});

  // Build the signed payload
  const signed_payload = `${timestamp}.${JSON.stringify(data)}`;

  // Validate the v0 signature
  if (signatureObject.v0) {
    const expectedSignature = crypto
      .createHmac('sha256', clientSecret)
      .update(signed_payload)
      .digest('hex');

    return signatureObject.v0 === expectedSignature;
  }

  return false;
}

Terminology

Urban Sharing APIs refer to docks, dock groups and vehicles as our platform is designed to support multiple modes of transport. In the case of bike share systems, docks are individual bike parking spots, dock groups are stations and vehicles are bikes.


Getting Started

Get vehicle by ID

Vehicles can be retrieved via the GET /vehicles/{vehicleId} endpoint. The endpoint will return the vehicle details.

Find vehicle

Get vehicle by QR code

Vehicles can be retrieved via the GET /vehicles/qr/{qrCode} endpoint. The endpoint will return the vehicle details.

Find vehicle by QR code

Get vehicle by GBFS ID

Vehicles can be retrieved via the GET /vehicles/gbfs/{gbfsId} endpoint. The endpoint will return the vehicle details.

Find vehicle by GBFS ID

Starting a trip

Trips are started via the POST /dockgroups/{dockGroupId}/trips

Start dock group trip

and POST /vehicles/{vehicleId}/trips endpoints.

Start vehicle trip

The endpoints accept a vehicle ID or station ID. The response will contain a trip ID that can be used to monitor the status of the trip. If the vehicle has a QR code, you should use GET /vehicles/qrcodes/{qrCode} to look up the vehicle ID.

Find trip

Trips can be found via the GET /trips/{tripId} endpoint. The endpoint will return the current state of the trip.

Find trip

Monitoring trip status

All ongoing trips report their status via the Maas Webhook. See the Maas Webhook API documentation for more information.

Updating trip state

The trip state can be updated via the PATCH /trips/{tripId} endpoint. Not all states are available for all Vehicle types. If an action is not supported, an error will be returned.

Update trip state

Vehicle damage reporting

Each vehicle type has a unique set of damages that can be reported. To obtain the list of damages use GET /vehicles/{vehicleId}/damagereports/types. Vehicle damage can be reported via the POST /vehicles/{vehicleId}/damagereports endpoint.

Damage types

Vehicle reservation

Vehicle reservations can be created via the POST /vehicles/{vehicleId}/reservations endpoint. The reservation will be valid for a set period of time. The reservation can be canceled via the DELETE /vehicles/{vehicleId}/reservations endpoint.

Vehicle reservation

Retrieving product details

Product details can be retrieved via the GET /products/{productId} endpoint.

Product list

Managing penalties

Penalties can be managed via the GET /users/{userId}/penalties endpoint. The endpoint will return a list of penalties for the user. Penalties can be added via the POST /users/{userId}/penalties endpoint. Penalties can be resolved via the PATCH /users/{userId}/penalties/{penaltyId} endpoint.

Penalties

Example flow

The following is an example flow for starting a trip using a QR code:

Example flow


Personally Identifiable Information (PII)

When starting a trip you must provide a unique user ID. This is the ID used to identify the user in your system. Urbansharing uses our own user ID linked to your user ID. If a user with the ID you provide does not exist in the Urban Sharing system, it will be created. The API will only return the IDs provided by the client. Urban Sharing complies with GDPR and will not store any PII data about your users, except when provided by you explicitly.


Trips

Update Trip

Updates a trip.

Authorizations:
bearer
path Parameters
tripId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
update
required
string
Enum: "pause" "resume" "cancel" "end"

Set a new trip state. Note that not all states are supported by all vehicle types.

userId
string

Optional User ID. We will validate that the trip belongs to this user, and reject the update if it does not.

object

User position

required
object

GeoJson Position

type
required
string
Default: "Point"

GeoJSON type

coordinates
required
Array of numbers

Coordinates in the form of [longitude, latitude]

accuracyRadiusMeters
number

The accuracy in meters of the user position

stateTransitionReason
string
Enum: "cancelled_by_administrator" "time_limit_exceeded" "vehicle_communication_timeout" "station_communication_timeout" "user_interaction_timeout" "vehicle_taken_by_administrator" "vehicle_moved_to_operation_location" "vehicle_decommissioned" "illegal_parking"

The reason why the state transistioned to the current state.

stateTransitionComment
string

Text describing the reason why the transition occurred

Responses

Request samples

Content type
application/json
{
  • "update": "end",
  • "userId": "string",
  • "userPosition": {
    },
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string"
}

Response samples

Content type
application/json
{
  • "code": "invalid_location",
  • "message": "An error occured"
}

Get Trip

Returns a trip based on ID

Authorizations:
bearer
path Parameters
tripId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "pricing": {
    }
}

Reservations

Get a vehicle reservation

Returns a reservation based on the id

Authorizations:
bearer
path Parameters
reservationId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "cancelledAt": "2019-08-24T14:15:22Z"
}

Cancel a vehicle reservation

Cancels an existing vehicle reservation

Authorizations:
bearer
path Parameters
reservationId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "cancelledAt": "2019-08-24T14:15:22Z"
}

Payments

Create Subscription Order

Creates a subscription order for the specified product.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

locale
required
string
Request Body schema: application/json
required
productId
required
string

Product ID to create subscription for

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "productId": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Create Wallet Deposit Order

Creates an order to deposit funds into the user wallet.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

locale
required
string
Request Body schema: application/json
required
amount
number

Amount to deposit into wallet

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Create Voucher Code Order

Creates an order for voucher/gift codes.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

locale
required
string
Request Body schema: application/json
required
customerEmail
required
string

Customer email address

required
Array of objects (OrderLineInputDto)

Order lines with product and quantity

Array
productId
required
string

Product ID

quantity
required
number >= 1

Quantity

receiptEmail
string

Email to send receipt to

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "customerEmail": "string",
  • "orderLines": [
    ],
  • "receiptEmail": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

List Orders

Returns a paginated list of user orders.

Authorizations:
bearer
query Parameters
statuses
Array of strings
Items Enum: "pending" "completed" "cancelled" "failed"

Filter by order statuses

limit
number
Default: 20

Maximum number of results to return

offset
number
Default: 0

Number of results to skip

orderBy
string
Enum: "createdAt" "completedAt"

Field to sort by

orderDirection
string
Enum: "asc" "desc"

Sort direction

userId
required
string

User ID

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "paginationInfo": {
    }
}

Get Order

Returns a single order by its token.

Authorizations:
bearer
path Parameters
token
required
string
query Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Apply Discount Code

Applies a discount code to an existing unpaid order.

Authorizations:
bearer
path Parameters
orderId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
code
required
string

Discount code to apply

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Remove Discount Code

Removes the applied discount code from an order.

Authorizations:
bearer
path Parameters
orderId
required
string
query Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string",
  • "status": "pending",
  • "amount": 0,
  • "amountWithoutVat": 0,
  • "currency": "string",
  • "createdAt": "string",
  • "completedAt": "string",
  • "unpaid": true,
  • "vatAmount": 0,
  • "vatRate": 0,
  • "availablePaymentMethods": [
    ],
  • "orderLines": [
    ],
  • "discount": {
    }
}

Pay

Initiates payment for an order or invoice.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

locale
required
string
Request Body schema: application/json
required
documentId
required
string

Document ID (order or invoice ID)

documentType
required
string
Enum: "order" "invoice"

Document type

required
object

Payment parameters

selectedPaymentMethod
required
string
Enum: "card" "wallet" "blik" "any"

Payment method to use

enableAutoRenew
boolean

Enable auto-renewal for subscriptions

save
boolean

Save payment method for future use

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "documentId": "string",
  • "documentType": "order",
  • "params": {
    },
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "publishableKey": "string",
  • "clientSecret": "string",
  • "customerRef": "string",
  • "customerKey": "string",
  • "webUrl": "string",
  • "paymentMethodRef": "string",
  • "orderToken": "string",
  • "state": "CREATED",
  • "errorCode": "string",
  • "message": "string",
  • "description": "string"
}

Get Payment Methods

Returns the current payment methods for the user.

Authorizations:
bearer
query Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Add Payment Method

Initiates the flow to add a new payment method.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

locale
required
string
Request Body schema: application/json
required
object

Redirect paths

successPath
required
string

URL to redirect to on success

cancelPath
required
string

URL to redirect to on cancel

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "paths": {
    },
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "webUrl": "string",
  • "provider": "stripe",
  • "url": "string",
  • "setupToken": "string",
  • "sessionId": "string",
  • "publishableKey": "string",
  • "clientSecret": "string"
}

Replace Payment Method

Initiates the flow to replace the existing payment method.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

locale
required
string
Request Body schema: application/json
required
object

Redirect paths

successPath
required
string

URL to redirect to on success

cancelPath
required
string

URL to redirect to on cancel

userId
required
string

User ID

Responses

Request samples

Content type
application/json
{
  • "paths": {
    },
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "webUrl": "string",
  • "provider": "stripe",
  • "url": "string",
  • "setupToken": "string",
  • "sessionId": "string",
  • "publishableKey": "string",
  • "clientSecret": "string"
}

Remove Payment Method

Removes the user payment method.

Authorizations:
bearer
query Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "code": "ERR_PAYMENT_ERROR",
  • "message": "Payment processing failed"
}

Products

Get Products

Returns all products available

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Users

Get User Trips

Returns all historical and current trips of a user

Authorizations:
bearer
path Parameters
userId
required
string
query Parameters
states
Array of strings
Items Enum: "starting" "in_progress" "on_hold" "completed" "cancelled"

Example: states[]=completed&states[]=cancelled

The trip states to filter by

from
required
string <date-time>

The start date to filter trips from

to
string <date-time>

The end date to filter trips until

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get User Reservations

Returns all active vehicle reservations for a user (excludes completed and cancelled)

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get User Statistics

Returns aggregated statistics for a user including distance, trips, CO2 saved, calories burned, and spending.

Authorizations:
bearer
path Parameters
userId
required
string
query Parameters
from
required
string <date-time>

The start date to filter from

to
string <date-time>

The end date to filter until

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "totalTrips": 42,
  • "totalDistanceKm": 123.45,
  • "totalRidingTimeSec": 3600,
  • "co2SavedGrams": 14814,
  • "caloriesBurned": 3703,
  • "totalSpentCents": 5000,
  • "currency": "NOK"
}

Get User Subscription

Returns the current active subscription for a user, or 404 if no active subscription exists.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "enabled": true,
  • "validFrom": "2024-01-01T00:00:00.000Z",
  • "validTo": "2024-12-31T23:59:59.999Z",
  • "product": {
    },
  • "isCancellable": true
}

Cancel User Subscription

Cancels the current active subscription for a user. Only subscriptions for free products or products marked as publicly cancellable can be cancelled.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Create User

Creates a user in the Urban Sharing system if they do not already exist. Returns the user profile.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": "user_12345"
}

Get User Onboarding

Returns the current onboarding state of a user.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Name

Submit the first and last name for the onboarding step.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
firstName
required
string

First name

lastName
required
string

Last name

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Doe"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Gender

Submit the gender for the onboarding step.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
gender
required
string
Enum: "male" "female" "other"

Gender

Responses

Request samples

Content type
application/json
{
  • "gender": "male"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Phone Number

Submit the phone number for the onboarding step.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
phoneNumber
required
string

The phone number

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "+4712345678"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Email

Submit the email address for the onboarding step.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
email
required
string

The email address

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Street Address

Submit the street address for the onboarding step.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
streetAddress
required
string

Street address line

streetAddress2
string

Second address line

streetAddress3
string

Third address line

postalCode
required
string

Postal code

city
required
string

City

countryCode
string

Country code (ISO 3166-1 alpha-2)

Responses

Request samples

Content type
application/json
{
  • "streetAddress": "Storgata 1",
  • "streetAddress2": "Apt 2",
  • "streetAddress3": "Building C",
  • "postalCode": "0182",
  • "city": "Oslo",
  • "countryCode": "NO"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Update Personal Number

Submit the personal identification number for the onboarding step.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
personalNumber
required
string

The personal identification number (national ID)

Responses

Request samples

Content type
application/json
{
  • "personalNumber": "12345678901"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Accept Privacy Policy

Accept the privacy policy and submit any additional legal consent checkboxes.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
accepted
required
boolean

Whether the user accepted the privacy policy

version
string

Version of the privacy policy accepted

Array of objects (LegalConsent)

Additional legal consent checkboxes

Array
key
required
string

Identifier for the legal consent checkbox

accepted
required
boolean

Whether the user accepted this consent

Responses

Request samples

Content type
application/json
{
  • "accepted": true,
  • "version": "2026-03-01",
  • "legalConsents": [
    ]
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Accept Terms and Conditions

Accept the terms and conditions.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
accepted
required
boolean

Whether the user accepted the terms and conditions

version
string

Version of the terms and conditions accepted

Responses

Request samples

Content type
application/json
{
  • "accepted": true,
  • "version": "2026-03-01"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Acknowledge Tutorial

Mark the tutorial as acknowledged.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
acknowledged
required
boolean

Whether the user acknowledged the tutorial

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Start Verify Phone Number

Start verification of the phone number. Returns a verification state, TTL, and code length.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
phoneNumber
required
string

The phone number

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "+4712345678"
}

Response samples

Content type
application/json
{
  • "state": "string",
  • "ttl": 0,
  • "length": 0
}

Verify Phone Number

Complete verification of the phone number by submitting the verification code.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
state
required
string

Verification state

code
required
string

The verification code

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Start Verify Email

Start verification of the email address. Returns a verification state, TTL, and code length.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
email
required
string

The email address

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "state": "string",
  • "ttl": 0,
  • "length": 0
}

Verify Email

Complete verification of the email address by submitting the verification code.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
state
required
string

Verification state

code
required
string

The verification code

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Verify Street Address

Trigger verification of the street address.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

Verify Personal Number

Trigger verification of the personal identification number.

Authorizations:
bearer
path Parameters
userId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "pending": [
    ],
  • "data": {
    }
}

CRM

Get CRM Settings

Returns CRM configuration including provider type, app ID, and computed user hash for identity verification.

path Parameters
systemId
required
string
query Parameters
userId
required
string
Example: userId=12345

User ID to generate hash for

platform
required
string
Enum: "ios" "android" "web"
Example: platform=ios

Platform type for selecting the appropriate verification secret

Responses

Response samples

Content type
application/json
{
  • "provider": "intercom",
  • "appId": "abc123xyz",
  • "token": "a1b2c3d4e5f6..."
}

Vehicles

Get Vehicles

Return all vehicles with detailed information.

This endpoint is designed to accept requests directly from end-user devices, whether directly from apps or through your own backend acting as a proxy.

It can sustain any level of traffic without having to think about request rates, limits, caching, or other scale optimizations.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get Vehicle by QR code

Returns vehicle data based on its QR code.

Authorizations:
bearer
path Parameters
qrCode
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "model": {
    },
  • "status": "available",
  • "state": "docked",
  • "unavailabilityReasons": [
    ],
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "location": {
    },
  • "qrCode": "string",
  • "isReserved": true,
  • "trip": {
    }
}

Get Vehicle by GBFS ID Deprecated

Returns vehicle data based on the its GBFS ID.

Authorizations:
bearer
path Parameters
gbfsId
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "model": {
    },
  • "status": "available",
  • "state": "docked",
  • "unavailabilityReasons": [
    ],
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "location": {
    },
  • "qrCode": "string",
  • "isReserved": true,
  • "trip": {
    }
}

Get Vehicle by ID

Returns vehicle data based on the its ID.

Authorizations:
bearer
path Parameters
id
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "model": {
    },
  • "status": "available",
  • "state": "docked",
  • "unavailabilityReasons": [
    ],
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "location": {
    },
  • "qrCode": "string",
  • "isReserved": true,
  • "trip": {
    }
}

Start Vehicle Trip

Starts a vehicle trip.

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
userId
required
string

The ID of the user starting the trip. This is your unique user ID. If the user does not exist in the Urban Sharing system, it will be created.

productId
number

The optional ID of the product being used for the trip. If the product ID is valid, product validations will be performed before starting the trip (i.e. valid product, penalty points etc.). At the end of the trip, the product ID will be used to calculate the price and a summary will be sent to the users/invoices webhook. If no product ID is provided, it is the responsibility of the caller to manage pricing and penalties.

object

User position

required
object

GeoJson Position

type
required
string
Default: "Point"

GeoJSON type

coordinates
required
Array of numbers

Coordinates in the form of [longitude, latitude]

accuracyRadiusMeters
number

The accuracy in meters of the user position

userName
string

The name of the user starting the trip. Optionally provide this to help identify the user for customer support.

userEmail
string

The email address of the user starting the trip. Optionally provide this to help identify the user for customer support.

maxSpeedKmh
number

The maximum speed allowed for the trip in km/h. If not provided, the default speed limits will be used.

Responses

Request samples

Content type
application/json
{
  • "userId": "User12345",
  • "productId": 1,
  • "userPosition": {
    },
  • "userName": "Jane Doe",
  • "userEmail": "jane.doe@example.com",
  • "maxSpeedKmh": 20
}

Response samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "pricing": {
    }
}

Reserve a vehicle

Reserves a specific vehicle

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
userId
required
string

The ID of the user who is reserving the vehicle

productId
number

The optional ID of the product being used for the reservation. If the product ID is valid, product validations will be performed before starting the reservation. e.g. valid product, penalty points etc. At the end of the reservation/trip, the product ID will be used to calculate the price and a summary will be sent to the users/invoices webhook. If no product ID is provided, it is the responsibility of the caller to manage pricing and penalties.

Responses

Request samples

Content type
application/json
{
  • "userId": "435432",
  • "productId": 1
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "cancelledAt": "2019-08-24T14:15:22Z"
}

Get Damage Types

Gets the damage types for a vehicle.

Authorizations:
bearer
path Parameters
vehicleId
required
number
query Parameters
locale
required
string
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Create Damage Report

Creates a damage report for a vehicle.

Authorizations:
bearer
path Parameters
vehicleId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
userId
required
string

The ID of the user that is creating the report

damageTypeIds
required
Array of numbers

List of IDs that correspond to the damage types being reported

comment
string

An optional comment related to the damage

notifyOnRepair
boolean

Whether to notify the user when the vehicle has been repaired

Responses

Request samples

Content type
application/json
{
  • "userId": "2334235",
  • "damageTypeIds": [
    ],
  • "comment": "The rear wheel is broken",
  • "notifyOnRepair": true
}

Response samples

Content type
application/json
{
  • "code": "ERR_INVALID_DAMAGE_REPORT",
  • "message": "Invalid damage report data provided"
}

Dock groups

Get Dock Groups

Return all dock groups with availability information.

This endpoint is designed to accept requests directly from end-user devices, whether directly from apps or through your own backend acting as a proxy.

It can sustain any level of traffic without having to think about request rates, limits, caching, or other scale optimizations.

Authorizations:
bearer
query Parameters
superpowers
boolean

Whether this request is on behalf of a user with superpowers, which may return more information than for a general public user

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get Vehicle by Dock Group ID

Returns vehicle data based on the the Dock Group ID.

Authorizations:
bearer
path Parameters
dockGroupId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get Dock Group

Return one dock group with availability information, if it matches the same visibility rules as the list endpoint.

This endpoint is designed to accept requests directly from end-user devices, whether directly from apps or through your own backend acting as a proxy.

It can sustain any level of traffic without having to think about request rates, limits, caching, or other scale optimizations.

Authorizations:
bearer
path Parameters
dockGroupId
required
number
query Parameters
superpowers
boolean

Whether this request is on behalf of a user with superpowers, which may return more information than for a general public user

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "type": "virtual",
  • "state": "active",
  • "name": "58",
  • "title": "Railway Station North",
  • "subtitle": "Next to the big clock tower",
  • "address": "123 Railway St, Cityville",
  • "availabilityInfo": {
    },
  • "geometry": {
    }
}

Start Dock Group Trip

Starts a dock group trip.

Authorizations:
bearer
path Parameters
dockGroupId
required
number
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
userId
required
string

The ID of the user starting the trip. This is your unique user ID. If the user does not exist in the Urban Sharing system, it will be created.

productId
number

The optional ID of the product being used for the trip. If the product ID is valid, product validations will be performed before starting the trip (i.e. valid product, penalty points etc.). At the end of the trip, the product ID will be used to calculate the price and a summary will be sent to the users/invoices webhook. If no product ID is provided, it is the responsibility of the caller to manage pricing and penalties.

object

User position

required
object

GeoJson Position

type
required
string
Default: "Point"

GeoJSON type

coordinates
required
Array of numbers

Coordinates in the form of [longitude, latitude]

accuracyRadiusMeters
number

The accuracy in meters of the user position

userName
string

The name of the user starting the trip. Optionally provide this to help identify the user for customer support.

userEmail
string

The email address of the user starting the trip. Optionally provide this to help identify the user for customer support.

maxSpeedKmh
number

The maximum speed allowed for the trip in km/h. If not provided, the default speed limits will be used.

vehicleCategory
required
string
Enum: "bike" "ebike" "scooter" "ebike_with_childseat"

The type of vehicle required for the trip.

Responses

Request samples

Content type
application/json
{
  • "userId": "User12345",
  • "productId": 1,
  • "userPosition": {
    },
  • "userName": "Jane Doe",
  • "userEmail": "jane.doe@example.com",
  • "maxSpeedKmh": 20,
  • "vehicleCategory": "bike"
}

Response samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "pricing": {
    }
}

Areas

Get Areas

Get all areas with their configurations and schedules.

This endpoint is designed to accept requests directly from end-user devices, whether directly from apps or through your own backend acting as a proxy.

It can sustain any level of traffic without having to think about request rates, limits, caching, or other scale optimizations.

Authorizations:
bearer
query Parameters
types
Array of strings
Items Enum: "illegal_docking" "speed_limit" "no_entry"

Example: types[]=illegal_docking&types[]=speed_limit

The area configuration types to filter by

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

System

Get System

Return a specific system and its relevant information based on the system ID.

Authorizations:
bearer
query Parameters
superpowers
boolean

Whether this request is on behalf of a user with superpowers, which may return more information than for a general public user

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get System Alerts

Return alerts for the system.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Get systems

Returns all systems available to the user. Optionally filter by position to only return systems whose geometry contains the given coordinates.

Authorizations:
bearer
query Parameters
position
string
Example: position=59.9139,10.7522

Filter by position. Format: "lat,lng" (e.g., "59.9139,10.7522"). Only returns results whose geometry contains this position.

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

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

Webhook Interface

Trip event

Receive trip events from the MAAS API.

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
type
string

Event type identifier, present when the trip originates from Core

id
required
number

Trip ID

clientId
required
string

The API client ID used to start the trip

userId
required
string

The ID of the user that started the trip

state
required
string
Enum: "starting" "in_progress" "on_hold" "completed" "cancelled"

The current state of the trip

stateTransitionReason
string
Enum: "cancelled_by_administrator" "time_limit_exceeded" "vehicle_communication_timeout" "station_communication_timeout" "user_interaction_timeout" "vehicle_taken_by_administrator" "vehicle_moved_to_operation_location" "vehicle_decommissioned" "illegal_parking"

The reason why the state transistioned to the current state. Only present when an external event caused the state transition.

stateTransitionComment
string

Text describing the reason why the transition occurred

required
object

The location at which the trip was started

timestamp
required
string <date-time>

The date the location was updated.

object

GeoPosition is set if the location has a coordinate. This value is required if dockID is not set, but is optional if it is set.

required
object

GeoJson Position

streetAddress
string

Street address of the position if available

object

StatePosition is set if there was a position recorded together with the last state change. This is the position at the time of state change

required
object

GeoJson Position

streetAddress
string

Street address of the position if available

object

Information about the dock. This value is required if the geoPosition is not defined.

dockGroupId
required
number

The ID of the dock group that the dock belongs to.

dockGroupName
required
string

The name of the dock group that the dock belongs to.

dockNumber
required
number

The number of the dock.

object

The vehicle being used for the trip

id
required
number

Vehicle ID

name
required
string

Name of the vehicle

number
required
string

Number of the vehicle

vehicleCategory
required
string
Enum: "bike" "ebike" "scooter" "ebike_with_childseat"

Vehicle category

required
object

Asset model data for the vehicle

id
required
number

The unique identifier of the asset model

name
required
string

The internal name of the asset model

type
required
string
Enum: "bike" "ebike" "scooter" "bike_controller" "scooter_controller"

The type of the asset model

manufacturer
string

The manufacturer of the asset model

brand
string

The brand of the asset model

model
string

The model of the asset

category
string
Enum: "bike" "ebike" "scooter" "ebike_with_childseat"

The vehicle category of the asset model

hardwareBridge
string
Enum: "omni_lock" "segway_api" "axa" "pashley" "linka" "sharebike"

The hardware bridge type for this asset model

lockVisual
string
Enum: "ring_lock" "segway_bike"

The lock visual for this asset model

status
required
string
Enum: "available" "unavailable" "on_trip" "with_operator" "in_operation_location" "lost" "never_seen" "unknown" "decommissioned"

Current overall, simplified, status of the vehicle. The vehicle can only be used when "available"

state
required
string
Enum: "unknown" "awaiting_wake_event" "awaiting_wake_event_on_resume" "awaiting_vehicle_unlock" "awaiting_interaction_confirmation" "awaiting_unlock_interaction" "awaiting_vehicle_unlock_on_resume" "in_progress" "awaiting_bolt_lock_armed_to_pause" "awaiting_bolt_lock_to_pause" "on_hold" "awaiting_bolt_lock_armed_to_end" "awaiting_bolt_lock_to_end" "docked" "cancelling" "in_operation_location" "with_administrator" "awaiting_bolt_lock_armed_to_virtual_dock" "awaiting_bolt_lock_to_virtual_dock" "awaiting_vehicle_unlock_jammed" "awaiting_vehicle_unlock_on_resume_jammed" "awaiting_bolt_lock_to_end_jammed" "awaiting_bolt_lock_to_pause_jammed" "awaiting_bolt_lock_to_end_cancelling" "awaiting_bolt_lock_to_pause_cancelling" "docking_jammed" "docking_jammed_administrator" "docking_jammed_unknown" "docking_jammed_operation_location" "removed_jammed" "awaiting_lock_to_end" "awaiting_lock_to_pause" "awaiting_iot_unlock_interaction" "lost" "decommissioned" "awaiting_geoposition" "awaiting_geoposition_administrator"

Current detailed state of the vehicle.

unavailabilityReasons
Array of strings
Items Enum: "dock_state" "dock_broken" "dock_group_state" "vehicle_controller_state" "vehicle_controller_charge" "vehicle_battery_charge" "vehicle_blocked" "vehicle_broken" "vehicle_state"

If the status of the vehicle is not "available", unavailabilityReasons will contain the reason(s) why

batteryCharge
number

Last reported vehicle battery charge (%)

batteryRange
number

Battery charge in terms of range left (meters)

object

The location information of the vehicle

timestamp
required
string <date-time>

The date the location was updated.

object

GeoPosition is set if the location has a coordinate. This value is required if dockID is not set, but is optional if it is set.

object

StatePosition is set if there was a position recorded together with the last state change. This is the position at the time of state change

object

Information about the dock. This value is required if the geoPosition is not defined.

qrCode
string

The qr code of the vehicle

isReserved
required
boolean

Whether the vehicle is currently reserved or not

trip
object Recursive

Informtion about the trip, if the vehicle is currently on a trip

object

The location at which the trip ended

timestamp
required
string <date-time>

The date the location was updated.

object

GeoPosition is set if the location has a coordinate. This value is required if dockID is not set, but is optional if it is set.

required
object

GeoJson Position

streetAddress
string

Street address of the position if available

object

StatePosition is set if there was a position recorded together with the last state change. This is the position at the time of state change

required
object

GeoJson Position

streetAddress
string

Street address of the position if available

object

Information about the dock. This value is required if the geoPosition is not defined.

dockGroupId
required
number

The ID of the dock group that the dock belongs to.

dockGroupName
required
string

The name of the dock group that the dock belongs to.

dockNumber
required
number

The number of the dock.

totalDistance
number

The total distance travelled during the trip in meters

updatedAt
required
string <date-time>

The date when the trip was last updated

object

Pricing information for the trip

totalAmountIncludingVat
required
number

The total cost incurred for the trip in minor currency units

currency
required
string

The currency code

tripDurationMins
required
number

The duration of the trip in minutes

freeMinutesFromPriceMatrix
number

Free minutes included from the price matrix

freeMinutesPerDayUsed
number

Free minutes per day used from the product allowance

freeMinutesPerDayRemaining
number

Free minutes per day remaining after this trip

required
Array of objects (TripPricingOrderLineDto)

Breakdown of individual cost line items

Array
type
required
string

The type of the order line

quantity
required
number

The quantity of units

amount
required
number

The price per unit in minor currency units (e.g. cents/øre)

vatRate
required
number

The VAT rate applied

Responses

Request samples

Content type
application/json
{
  • "type": "MAAS_TRIP_STATE_UPDATE",
  • "id": 12345,
  • "clientId": "Client12345",
  • "userId": "User12345",
  • "state": "cancelled",
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string",
  • "startedAtLocation": {
    },
  • "vehicle": {
    },
  • "endedAtLocation": {
    },
  • "totalDistance": 12.55,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "pricing": {
    }
}

Reservation event

Receive reservation events from the MAAS API.

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
id
required
number

The ID of the reservation

vehicleId
number

The ID of the vehicle to be reserved. Required if dockGroupId is not provided. If both are provided, dockGroupId will be ignored

dockGroupId
number

The ID of the dock group from which to reserve the vehicle. Required if vehicleId is not provided

userId
required
string

The ID of the user who is reserving the vehicle

clientId
required
string

The API client ID used to create the reservation

createdAt
required
string <date-time>

The date and time the reservation was created

updatedAt
string <date-time>

The date and time the reservation was last updated

expiresAt
required
string <date-time>

The date and time the reservation expires

completedAt
string <date-time>

The date and time the reservation was completed

cancelledAt
string <date-time>

The date and time the reservation was cancelled

Responses

Request samples

Content type
application/json
{
  • "id": 2,
  • "vehicleId": 2,
  • "dockGroupId": 2,
  • "userId": "435432",
  • "clientId": "Client12345",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "cancelledAt": "2019-08-24T14:15:22Z"
}

User invoice event

Receive user invoice events from the MAAS API. Only applicable for trips that were started using a productId

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
userId
required
string

The ID of the user to be invoiced

productId
required
number

The ID of the product related to the invoice

tripId
number

The ID of the trip related to the invoice

reservationId
number

The ID of the reservation related to the invoice

currency
required
string

The currency used for the trip charges

required
Array of objects (MaasUserInvoiceOrderLine)

A breakdown of the costs incurred during the trip

Array
cost
required
number

The total cost of this part of the trip

defaultDescription
required
string

The title of the order line

type
required
string
Enum: "trip" "extended_rental" "free_floating_docking_fee" "free_minutes_per_day" "registration_fee" "reservation"

The type of the order line

Responses

Request samples

Content type
application/json
{
  • "userId": "user00002",
  • "productId": 24,
  • "tripId": 43424,
  • "reservationId": 34312,
  • "currency": "USD",
  • "orderLines": [
    ]
}

User penalty event

Receive user penalty events from the MAAS API. Only applicable for trips that were started using a productId

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
penaltyId
required
number

The ID of the penalty

userId
required
string

The ID of the user

penaltyType
required
string
Value: "trip_duration"

The type of penalty

penaltyPoints
required
number

The total number of penalty points incurred during this period of the trip

Responses

Request samples

Content type
application/json
{
  • "penaltyId": 214,
  • "userId": "47372",
  • "penaltyType": "trip_duration",
  • "penaltyPoints": 1
}

User message event

Receive user messages from the MAAS API.

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
userId
required
number

The ID of the user

defaultMessage
required
string

The message in the default language

messageType
required
string
Enum: "trip_time_warning" "trip_cancelled" "vehicle_incorrectly_parked" "reservation_cancelled" "illegal_parking"

The type of user message

Array of objects (UserMessageParameter)

Parameter values for the message

Array
key
required
string

The user message parameter key

value
required
string

The user message parameter value

Responses

Request samples

Content type
application/json
{
  • "userId": 94,
  • "defaultMessage": "Your bike was parked incorrectly at station - Central Station",
  • "messageType": "reservation_cancelled",
  • "parameters": [
    ]
}

Lost vehicle event

Receive lost vehicle updates. This event is fired when a vehicle whose last trip was with this client enters or leaves the lost state.

header Parameters
uowid
string

A globally unique unit of work ID generated by the client which allows Urban Sharing to track requests through our systems. If no header is provided it will be generated automatically at the time of arrival. The header and ID will be returned in the response.

Urbansharing-Signature
required
string

Used to verify the authenticity of the webhook request. For information about how to validate the signature, see here.

Request Body schema: application/json
required
clientId
required
string

The API client ID used to create the reservation

vehicleId
required
number

The ID of the vehicle

lost
required
boolean

Whether or not the vehicle is considred lost

Responses

Request samples

Content type
application/json
{
  • "clientId": "Client12345",
  • "vehicleId": 94,
  • "lost": true
}