API docs by Redocly

Urban Sharing - MAAS API (1.5.1)

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 changes 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 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 Authentication 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 locks, 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 their 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. Urban Sharing will never expose their internal user IDs, only the IDs provided by the client. Urban Sharing complies with GDPR and will not store any PII data about your users. The only information stored is the user ID and the user position if provided. The user position is only used for validation during trip state changes.


MAAS API

Get Vehicle by QR code

Returns vehicle data based on its QR code.

Authorizations:
bearer
path Parameters
qrCode
required
string
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.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "status": "available",
  • "unavailableReason": "dock_broken",
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "lastTripId": 324344
}

Get Vehicle by GBFS ID

Returns vehicle data based on the its GBFS ID.

Authorizations:
bearer
path Parameters
gbfsId
required
string
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.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "status": "available",
  • "unavailableReason": "dock_broken",
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "lastTripId": 324344
}

Get Vehicle by ID

Returns vehicle data based on the its ID.

Authorizations:
bearer
path Parameters
id
required
string
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.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Bike 1",
  • "number": "42",
  • "vehicleCategory": "ebike",
  • "status": "available",
  • "unavailableReason": "dock_broken",
  • "batteryCharge": 70,
  • "batteryRange": 4000,
  • "lastTripId": 324344
}

Start Dock Group Trip

Starts a dock group trip.

Authorizations:
bearer
path Parameters
dockGroupId
required
number
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.

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. Urban Sharing will never expose their internal user IDs, only the IDs provided by the client.

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

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": {
    },
  • "vehicleCategory": "bike"
}

Response samples

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

Start Vehicle Trip

Starts a vehicle trip.

Authorizations:
bearer
path Parameters
vehicleId
required
number
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.

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. Urban Sharing will never expose their internal user IDs, only the IDs provided by the client.

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

Responses

Request samples

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

Response samples

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

Reserve a vehicle

Reserves a specific vehicle

Authorizations:
bearer
path Parameters
vehicleId
required
number
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.

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 a vehicle reservation

Returns a reservation based on the id

Authorizations:
bearer
path Parameters
reservationId
required
string
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.

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

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

Get Damage Types

Gets the damage types for a vehicle.

Authorizations:
bearer
path Parameters
vehicleId
required
number
query Parameters
locale
required
string
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.

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

Request Body schema: application/json
required
userId
required
string

The ID of the user that is creating the report

damageTypeIds
required
Array of arrays

List of IDs that correspond to the damage types being reported

comment
string

An optional comment related to the damage

Responses

Request samples

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

Update Trip

Updates a trip.

Authorizations:
bearer
path Parameters
tripId
required
number
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.

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.

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",
  • "userPosition": {
    },
  • "stateTransitionReason": "cancelled_by_administrator",
  • "stateTransitionComment": "string"
}

Response samples

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

Find Trip

Returns a trip based on ID

Authorizations:
bearer
path Parameters
tripId
required
number
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.

Responses

Response samples

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

Find Products

Returns all products available

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

Responses

Response samples

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

Find User Penalties

Returns the active penalties accrued by a user

Authorizations:
bearer
path Parameters
userId
required
string
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.

Responses

Response samples

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

Add User Penalty

Adds a new penalty value to a user

Authorizations:
bearer
path Parameters
userId
required
string
required
object (MaasCreatePenalty)
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.

Responses

Response samples

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

Resolve User Penalty

Resolves a user penalty

Authorizations:
bearer
path Parameters
userId
required
string
penaltyId
required
number
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.

Responses

Response samples

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

MAAS Event Webhook

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

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

status
required
object

Current status of the vehicle. The vehicle can only be used when the status is "available"

unavailableReason
required
string
Enum: "dock_state" "dock_broken" "vehicle_broken" "vehicle_battery_charge" "vehicle_controller" "vehicle_controller_state" "vehicle_controller_power_state" "vehicle_controller_battery_charge" "vehicle_controller_battery_voltage" "vehicle_controller_serial_number" "vehicle_controller_ip" "vehicle_model" "vehicle_controller_model" "vehicle_reserved"

If the status of the vehicle is "unavailable", unavailableReason will contain the reason why

batteryCharge
number

Last reported vehicle battery charge

batteryRange
number

Battery charge in terms of range left (meters)

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

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

Responses

Request samples

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

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
}