Booking API

The Booking API allows you to integrate with Autopay to create anonymous parking permits (bookings) for a vehicle.


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


For migration from V1 to V2, see Migration guide

Access requirements


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