Permit API

The Permit API allows you to manage permits for a tenant in Autopay. Access to this API is given for a tenant.

By accessing or using the API, the integrator agrees to be bound by the terms and conditions of Permit API.

Access requirements:

Permit API

The Permit API enables tenants to manage permits given to end-users. Permits for end-users can be issued, updated and revoked.

Available resources:

GET - List all available permit allocations

This method allows you to get all available permit allocations that can be used to issue permits.

Endpoint

GET https://api.autopay.io/permit/v3/tenant_permit_allocations

Request parameters:

Successful response:

HTTP Code: 200 OK

Parameter Type Description
permit_allocation_id string ID of the permit allocation
permit_definition_name string Permit definition name
parking_spaces_count integer Parking spaces count
permit_count integer Permit count
issued_permit_count integer Issued permits count
valid_from datetime (ISO 8601) Time from which the permit is valid
valid_to datetime (ISO 8601) Time until which the permit is valid

Example successful response: 

[
    {
        "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
        "permit_definition_name": "Free parking from 5 to 9",
        "parking_spaces_count": 50,
        "permit_count": 25,
        "issued_permit_count": 10,
        "valid_from": "2018-06-19T00:00:00+0100",
        "valid_to": "2028-01-13T23:59:59+0100"
    }
]

GET - List all permits for a tenant

This method allows you to get all permits a tenant has issued to end users. Can be filtered by permit allocation.

Endpoint

GET https://api.autopay.io/permit/v3/tenant_issued_permits

Request parameters:

  • The HTTP headers must include a valid access token. The access token includes the tenant information.
  • Optional path parameter: permit_allocation_id - filter by permit allocation ID.

Example request

GET https://api.autopay.io/permit/v3/tenant_issued_permits?permit_allocation_id=f8ab6b8b-3b20-419a-9381-aec7d76ec2a6

Successful response:

HTTP Code: 200 OK

Parameter Type Description
permit_id string Unique permit ID that can be used to update or delete the permit
email string Customer e-mail address linked to their autopay.io account
permit_allocation_id string ID of the permit allocation that is used for the permit
permit_definition_name string Name of the permit allocation
valid_from datetime (ISO 8601) Time from which the permit is valid
valid_to datetime (ISO 8601) Time until which the permit is valid
activated boolean Permit is active when end user has an active autopay.io profile with a minimum of one car linked to it
activated_at datetime (ISO 8601) Date when the permit was activated. Equal to permit created date if the customer had an autopay.io account.

Example successful response: 

[
    {
        "permit_id": "dd0c3f60-b568-4d85-b5c0-93e5acf86426",
        "email": "client@autopay.io",
        "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
        "permit_definition_name": "Free parking from 5 to 9",
        "valid_from": "2018-06-19T00:00:00+0100",
        "valid_to": "2028-01-13T23:59:59+0100",
        "activated": true,
        "activated_at": "2022-04-26T15:00:00+0100"
    }
]

POST - Give permit to end-user

Method to give permit to end user.

Endpoint

POST https://api.autopay.io/permit/v3/end_user_permit

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.
Parameter Type Mandatory Description
permit_allocation_id string yes Permit allocation ID that is activated when permit is used. Get a list of applicable permits
email string yes Customer e-mail address linked to their autopay.io account
valid_from date (YYYY-MM-DD) yes Date from which the permit is valid. Must be today's date or later
valid_to date (YYYY-MM-DD) yes Date until which the permit is valid

Request example:

{
    "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
    "email": "client@autopay.io",
    "valid_from": "2018-06-19",
    "valid_to": "2025-12-19"
}

Successful response:

HTTP Code: 200 OK

Parameter Type Description
permit_id string Unique permit ID that can be used to update or delete the permit
email string Customer e-mail address linked to their autopay.io account
permit_allocation_id string ID of the permit allocation that is used for the permit
permit_definition_name string Name of the permit allocation
valid_from datetime (ISO 8601) Time from which the permit is valid
valid_to datetime (ISO 8601) Time until which the permit is valid
activated boolean Permit is active when end user has an active autopay.io profile with a minimum of one car linked to it
activated_at datetime (ISO 8601) Date when the permit was activated. Equal to permit created date if the customer had an autopay.io account.

Example successful response: 

{
    "permit_id": "dd0c3f60-b568-4d85-b5c0-93e5acf86426",
    "email": "client@autopay.io",
    "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
    "permit_definition_name": "Free parking from 5 to 9",
    "valid_from": "2018-06-18T00:00:00+0100",
    "valid_to": "2025-12-18T23:59:59+0100",
    "activated": true,
    "activated_at": "2022-04-26T15:00:00+0100"
}

PUT - Update end user permit

Method to update the validity period of the parking permit.

Endpoint

PUT https://api.autopay.io/permit/v3/end_user_permit/{permit_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.
  • The path must include the permit ID.
Parameter Type Mandatory Description
valid_from date (YYYY-MM-DD) no Must be the same date as before, todays date or future date. Will be the same date as before if it is not set
valid_to date (YYYY-MM-DD) yes Date until which the permit is valid

Request example:

{
    "valid_from": "2018-06-19",
    "valid_to": "2025-12-19"
}

Successful response:

HTTP Code: 200 OK

Parameter Type Description
permit_id string Unique permit ID that can be used to update or delete the permit
email string Customer e-mail address linked to their autopay.io account
permit_allocation_id string ID of the permit allocation that is used for the permit
permit_definition_name string Name of the permit allocation
valid_from datetime (ISO 8601) Time from which the permit is valid
valid_to datetime (ISO 8601) Time until which the permit is valid
activated boolean Permit is active when end user has an active autopay.io profile with a minimum of one car linked to it
activated_at datetime (ISO 8601) Date when the permit was activated. Equal to permit created date if the customer had an autopay.io account.

Example successful response: 

{
    "permit_id": "906bd463-a383-4caa-aae7-196aa8b769bc",
    "email": "client@autopay.io",
    "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
    "permit_definition_name": "Free parking from 5 to 9",
    "valid_from": "2018-06-18T00:00:00+0100",
    "valid_to": "2025-12-18T23:59:59+0100",
    "activated": false,
    "activated_at": null
}

DELETE - Remove end user permit

Method to remove permit from end user.

Endpoint

DELETE https://api.autopay.io/permit/v3/end_user_permit/{permit_id}

Request:

  • The HTTP headers must include a valid access token.
  • The path must include the permit ID.

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 ID-s:

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
fetch_tenant_issued_permits_error Error fetching tenant's issued permits.
fetch_tenant_allocations_error Error fetching tenant allocations.
allocate_end_user_permit_error Error allocating end user permit.
update_end_user_permit_error Error updating end user permit.
remove_end_user_permit_error Error removing end user permit.
operator_not_found_error Operator not found.
update_permit_allocation_request_failure Request failure when updating permit allocation
update_permit_allocation_failed_to_fetch_landlord Failed to fetch landlord
update_permit_allocation_failed_to_authorize_for_landlord The landlord is not under the given operator
update_permit_allocation_api_access_not_enabled_for_operator API access is not enabled for landlord
delete_permit_allocation_request_failure Request failure when updating permit allocation
delete_permit_allocation_failed_to_fetch_landlord Failed to fetch landlord
delete_permit_allocation_failed_to_authorize_for_landlord The landlord is not under the given operator
delete_permit_allocation_api_access_not_enabled_for_operator API access is not enabled for landlord
missing_operator_token_error Missing operator in access token
missing_landlord_token_error Missing landlord in access token