Booking Quickstart Guide

Shared Mobility’s Booking API allows Fleet Utilization OBD-II customers to send additional booking or “rental” data to pair their vehicle trip history to their users or “drivers.” This documentation includes everything needed to successfully pair users to vehicles for an allotted amount of time. If you have any additional questions around using the Booking API, please contact your Customer Success team.

All requests to Arity require authentication and all applications must be registered with us.

1. Client ID and Client Secret
   Get your Client ID and Client Secret. These have already been created and approved by Arity, and have been sent to you. Contact us if you need help locating them.
2. Access token
   Generate an access token with the Authorization API. This access token expires every hour and must be passed in the header of all subsequent API calls.

Use the POST /generateToken endpoint to generate a b2b-scope access token by sending your Client ID and Client Secret.

3. User
   We require creating a user to start and end a booking if the user is not already in Arity's system. In Fleet Utilization, a user refers to the driver that books or “rents” a vehicle. Neither dateOfBirth nor homeZip are required to create a user or to pair them to a vehicle. You can specify the userID, or if you leave it blank, Arity will generate one for you. To create a user with an auto-generated ID, leave the userID field NULL or remove the key-value pair entirely. If you specify a userID, there are no input validations. An auth token is required for this call.

Use the POST /users/{userId} endpoint to create a new user.

4. Vehicle
   In addition to userID, we require creating a vehicle to start and end a booking if the vehicle is not already in Arity's system. Using a Vehicle Identification Number, the VIN must be 17 alphanumeric digits in length to be considered valid. An auth token is required for this call.

Use the POST /vehicles/{vin} method to create a new VIN.

5. Start Booking
   Once a userID and a VIN are created, you can start a booking. Along with the VIN, we require a startTimestamp. The bookingID, userID, deviceID and estimatedEndTimestamp are considered optional. If you choose to provide an estimatedEndTimestamp, it must occur after the startTimestamp to be considered valid. If the VIN that is passed is not already paired with a deviceID (IMEI), a deviceID must be passed. If the deviceID that is passed differs from the deviceID that is currently paired with the VIN, the pairing will update. The startTimestamp must be in Epoch format (XX seconds since January 1, 1970) and it indicates the actual time a booking started. The estimatedEndTimestamp must also be in Epoch format and it indicates the estimated time a booking will end. You can specify the bookingID and/or the userID if you prefer; however, if you leave either blank, Arity will generate them for you. To create a booking or a user with an auto-generated ID, leave either field NULL or remove the key-value pair entirely. An auth token is required for this call.

Use the POST /bookings endpoint to start a new booking.

6. End Booking
   Once a booking has started and a user has returned the vehicle, you can then end a booking. We require the same bookingID that was either specified or generated while starting the booking. We require an actualEndTimestamp to end a booking and it must occur after the original startTimestamp in the POST /booking call. It startTimestamp must be in Epoch format and it indicates the actual time a booking ends. An auth token is required for this call.

Use the PUT /bookings/{bookingId} endpoint to end a booking that has already been started.