A booking is a type of permit that is anonymous and not visible to existing clients in autopay.io. It is tied to the vehicle. Typical usage for a booking is providing paid parking for a hotel guests who does not wish to go through the sign up procedure.
Available resources
- GET - get a list of permit definitions that can be used to create a booking
- GET - get a status of a booking
- GET - get booking's availability
- POST - request a booking for a vehicle
- PUT - update an existing booking
- DELETE - delete a booking
- Error handling
For migration from V1 to V2, see Migration guide
Access requirements
- A valid authentication token is required to access the API. How to authenticate your application.
- Access to the Booking API is offered as a paid service. Please contact your Autopay representative for details.
- There is a 15-minute query rate limit per booking on the GET Get a status of a booking endpoint.
GET Get a status of a booking
To see the restrictions applied to change a booking, please see PUT - update an existing booking.
This method allows you to retrieve a status of a booking to see if it exists and whether it has been used. There are four different statuses:
NOT_USED
- A booking that is still valid but has no parking session linked to it.IN_USE
- A booking that has a parking session linked to it and is still valid.USED
- A booking that has a parking session linked to it and is no longer valid.EXPIRED
- A booking that does not have a parking session linked to it and is no longer valid (expired due to end of validity or due to expiration time).Endpoint
GET https://api.autopay.io/booking/v2/{id}/status
Request parameters
- The HTTP headers must include a valid access token with scope:
permit_booking
.
Success response
HTTP Code: 200 OK
Parameter | Type | Description |
---|---|---|
status | string | Status of a booking |
Example success response
{
"status": "USED"
}
GET Get a list of permit definitions
This method allows you to retrieve a list of permit definitions that can be used to create a booking. Permit definitions are managed by Autopay operators.
Endpoint
GET https://api.autopay.io/booking/v2/permit_definitions
Request parameters
- The HTTP headers must include a valid access token with scope:
permit_booking
.
Success response
HTTP Code: 200 OK
Parameter | Type | Description |
---|---|---|
id | string | ID of the parking permit definition provided by the operator of the parking venue |
name | string | Name of the parking permit definition provided by the operator of the parking venue |
tenantName | string | Name of the tenant |
accessLimit | object | Maximum amount of bookings that can be active at once for each day |
mon | integer | Limit for Monday |
tue | integer | Limit for Tuesday |
wed | integer | Limit for Wednesday |
thu | integer | Limit for Thursday |
fri | integer | Limit for Friday |
sat | integer | Limit for Saturday |
sun | integer | Limit for Sunday |
Example success response
[
{
"id": 17,
"name": "Hotel guest parking in zone 215",
"tenantName": "Example tenant",
"accessLimit": null
},
{
"id": 7,
"name": "Airport - Online booking",
"tenantName": "Example tenant",
"accessLimit": {
"mon": 1,
"tue": 1,
"wed": 1,
"thu": 2,
"fri": 1,
"sat": 1,
"sun": 1
}
}
]
GET Get booking's availability
This method allows you to retrieve available booking limit and it's validity period, if there is no available limit then it returns the time when there is one.
Endpoint
GET https://api.autopay.io/booking/v2/products/availability/validFrom/{validFrom}
Request parameters
- The HTTP headers must include a valid access token with scope:
permit_booking
. - The request path must include valid from datetime in ISO 8601 format.
Success response
HTTP Code: 200 OK
Parameter | Type | Description |
---|---|---|
available | boolean | Availability of booking |
limitAmount | integer | Amount of available bookings |
validFrom | datetime (ISO 8601) | Start time of availability check's validity |
validTo | datetime (ISO 8601) | End time of availability check's validity |
Example success response
{
"available": true,
"limitAmount": 5,
"validFrom": "2021-11-17T13:00:00+02:00",
"validTo": "2021-11-18T13:00:00+02:00"
}
POST Request a booking
This method allows you request a booking for a vehicle. A booking can start and end at a specific time (fixed booking) or be relative to when the vehicle enters the parking venue (entry booking). Both types can be applied wither beforehand or when the parking is already in progress.
Endpoint
POST https://api.autopay.io/booking/v2
Request parameters
- The request body must be in JSON format and HTTP headers must include
Content-Type: application/json
. - The HTTP headers must include a valid access token with scope:
permit_booking
.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | yes | Booking type. Supported values: ENTRY or FIXED |
validFrom | datetime (ISO 8601) | no | Time from which the booking is valid. Mandatory when type is FIXED |
validTo | datetime (ISO 8601) | no | Time until which the booking is valid. Mandatory when type is FIXED |
duration | integer | no | Duration of booking validity in seconds. Mandatory when type is ENTRY |
comment | string | no | Booking comment |
licencePlate | string | no | Licence plate number of the end-user's vehicle. Mandatory when booking is not anonymous. |
permitDefinitionId | integer | yes | ID of the parking permit definition that should be used for the booking. GET a list of permit definitions |
usableOnce | boolean | no | When true the booking can only be used once. When false multiple entries to the parking venue during the booking validity period are permitted. Default: false |
payment | |||
amount | decimal | no | Total sum charged for the booking |
currency | string | no | Currency of the payment for the booking |
customer | |||
string | no | E-mail address of the end-user | |
mobile | string | no | Telephone number of the end-user |
travelInformation | |||
flightId | string | no | Flight number of the end-user |
anonymousBooking | boolean | no | When the vehicle is not known at the time of booking creation, anonymous booking can be created without a licence plate and the customer can later link the booking to a vehicle using a kiosk. |
expirationTime | datetime (ISO 8601) | no | An expiration time can only be specified for ENTRY-type bookings. A client must take the booking into use before the expiration time. If the expiration time is not specified, a 1-year default expiration time is applied. |
Example request
{
"type": "FIXED",
"validFrom": "2017-12-23T12:05:56.833Z",
"validTo": "2017-12-30T12:05:56.833Z",
"duration": null,
"licencePlate": "123ABC",
"permitDefinitionId": 17,
"payment": {
"amount": 370,
"currency": "NOK"
},
"customer": {
"email": "test@test.com",
"mobile": "+47123456"
},
"travelInformation": {
"flightId": "AB123"
}
}
Success response
HTTP Code: 200 OK
Parameter | Type | Description |
---|---|---|
bookingId | string | ID of this booking |
type | string | Booking type |
validFrom | datetime (ISO 8601) | Time from which the booking is valid. Only present when type is FIXED |
validTo | datetime (ISO 8601) | Time until which the booking is valid. Only present when type is FIXED |
duration | integer | Duration of booking validity in seconds. Only present when type is ENTRY |
licencePlate | string | Licence plate number of the end-user's vehicle |
permitDefinitionId | integer | ID of the parking permit definition that should be used for the booking |
usableOnce | boolean | Is the booking usable only once |
bookingActivationCode | string | If the booking type is anonymous, activation code can be used for activating the booking using a kiosk |
expirationTime | datetime (ISO 8601) | ENTRY type booking expiration time. Not returned with FIXED bookings. |
Example success response
{
"bookingId": "123456",
"type": "FIXED",
"validFrom": "2017-12-23T12:05:56+0000",
"validTo": "2017-12-30T12:05:56+0000",
"licencePlate": "123ABC",
"permitDefinitionId": 17,
"usableOnce": false
}
PUT Update an existing booking
This method allows you to edit booking information. The following restrictions are applied when changing a booking:
- One cannot change a booking’s id, type, or anonymous flag.
- The valid from time and license plate number cannot be changed when the booking is in use (status IN_USE).
- Bookings with statuses USED and EXPIRED cannot be changed.
Endpoint
PUT https://api.autopay.io/booking/v2/{id}
Request parameters
- The request body must be in JSON format and HTTP headers must include
Content-Type: application/json
. - The HTTP headers must include a valid access token with scope:
permit_booking
. - The request path must include permit id.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | yes | Booking type. Supported values: ENTRY or FIXED |
validFrom | datetime (ISO 8601) | no | Time from which the booking is valid. Mandatory when type is FIXED |
validTo | datetime (ISO 8601) | no | Time until which the booking is valid. Mandatory when type is FIXED |
duration | integer | no | Duration of booking validity in seconds. Mandatory when type is ENTRY |
comment | string | no | Booking comment |
licencePlate | string | no | Licence plate number of the end-user's vehicle. Mandatory when booking is not anonymous. |
permitDefinitionId | integer | yes | ID of the parking permit definition that should be used for the booking. GET a list of permit definitions |
usableOnce | boolean | no | When true the booking can only be used once. When false multiple entries to the parking venue during the booking validity period are permitted. Default: false |
payment | |||
amount | decimal | no | Total sum charged for the booking |
currency | string | no | Currency of the payment for the booking |
customer | |||
string | no | E-mail address of the end-user | |
mobile | string | no | Telephone number of the end-user |
travelInformation | |||
flightId | string | no | Flight number of the end-user |
expirationTime | datetime (ISO 8601) | no | An expiration time can only be specified for ENTRY-type bookings. A client must take the booking into use before the expiration time. If the expiration time is not specified, a 1-year default expiration time is applied. |
Example request
{
"type": "FIXED",
"validFrom": "2017-12-23T12:05:56.833Z",
"validTo": "2017-12-30T12:05:56.833Z",
"duration": null,
"licencePlate": "123ABC",
"permitDefinitionId": 32,
"payment": {
"amount": 370,
"currency": "NOK"
},
"customer": {
"email": "test@test.com",
"mobile": "+47123456"
},
"travelInformation": {
"flightId": "AB123"
}
}
Success response
HTTP Code: 200 OK
Parameter | Type | Description |
---|---|---|
bookingId | string | ID of this booking |
type | string | Booking type |
validFrom | datetime (ISO 8601) | Time from which the booking is valid. Only present when type is FIXED |
validTo | datetime (ISO 8601) | Time until which the booking is valid. Only present when type is FIXED |
duration | integer | Duration of booking validity in seconds. Only present when type is ENTRY |
licencePlate | string | Licence plate number of the end-user's vehicle |
permitDefinitionId | integer | ID of the parking permit definition that should be used for the booking |
usableOnce | boolean | Is the booking usable only once |
bookingActivationCode | string | If the booking type is anonymous, activation code can be used for activating the booking using a kiosk |
expirationTime | datetime (ISO 8601) | ENTRY type booking expiration time. Not returned with FIXED bookings. |
Example success response
{
"bookingId": "123456",
"type": "FIXED",
"validFrom": "2017-12-23T12:05:56+0000",
"validTo": "2017-12-30T12:05:56+0000",
"licencePlate": "123ABC",
"permitDefinitionId": 17,
"usableOnce": false
}
DELETE Delete booking
This method allows you to delete end-users booking. Only unused bookings can be deleted.
Endpoint
DELETE https://api.autopay.io/booking/v2/{id}
Request parameters
- The HTTP headers must include a valid access token with scope:
permit_booking
. - The request path must include permit id.
Request example
DELETE https://api.autopay.io/booking/v2/6648392
Success response
HTTP Code: 200 OK
Error messages
Parameter | Type | Description |
---|---|---|
error_id | string | Specific code of error. See below for possible values |
message | string | Description of error |
description | string | Optional value. Additional description of error |
Example error response
{
"error_id": "authentication_error",
"message": "No access token present in header!"
}
Possible error IDs
Error id | Explanation |
---|---|
forbidden | Unauthorized |
internal_server_error | Internal server error |
missing_property | A required property in request is missing |
message_not_readable | A problem with the request body |
method_not_supported | Used REST method not supported |
argument_type_mismatch | A request argument is of incorrect type |
server_communication_error | Error communication with server |
invalid_type_error | Invalid value for 'type' |
invalid_fixed_type_error | With type FIXED valid_from and valid_to must not be null and duration must be null |
invalid_entry_type_error | With type ENTRY valid_from and valid_to must be null and duration must not be null |
operator_not_found_error | Operator not found |
Migration guide
Migration from V1 to V2 (current version) and version differences
- GET v2/permit_definitions
- renamed from v1/products
- POST /v2
- renamed from /v1/permit
- renamed response parameter productId to permitDefinitionId
- added optional anonymous_booking parameter to request and booking_activation_code to response if that parameter is true
- PUT /v2/{permitId}
- renamed from /v1/permit/{permitId]
- renamed response parameter productId to permitDefinitionId
- Error handling
- error_id (string) is returned instead of error_code (integer)