Permit Management API

The Permit Management API allows you to manage permits & permit allocations for organizations in Autopay.

Access requirements:

Permit Allocation Management

Permit allocation management can be used by landlords to issue permit allocations to tenant organizations (full access tenant) or individuals (basic tenant). The API supports creating, updating and deleting permit allocations as well as creating and querying tenants.

Available operations:

Permit Management

Permit management enables tenants to manage their permits via this API. Permits for end-uers can be issued, updated and revoked.

Available resources:

Permit Allocation Management

Get the available permit definitions

This method allows you to get all available permit definitions for a landlord that can be used to issue permit allocations.

Endpoint

GET https://api.autopay.io/permit/v2/landlord/{landlordId}/permitDefinitions

Request parameters:

  • The HTTP headers must include a valid access token.
  • The access token must include operator_id and landlord_id.
  • landlordId is the ID of the landlord for which this query should be run.

Success response:

HTTP Code: 200 OK

Parameter Type Description
landlord_id string The ID of the landlord that the following permit definitions belong to.
permit_definitions array The actual list of permit definitions that are available under the given landlord.
permit_definition_id string Permit definition ID
permit_definition_name string Permit definition name
facilities array The list of facilities in which this kind of permit is valid.
facility_code string The ID (code) of the facility
facility_name string The display name of the facility
zones array The list of zones within the facility where this kind of permit is valid.
zone_code string The ID (code) of the zone
zone_name string The display name of the zone

Example success response:

    
    {
        "landlord_id": "12ddfg1-2131533-qd2461r1",
        "permit_definitions": [
            {
                "permit_definition_id": "1412321",
                "permit_definition_name": "Free parking from 5 to 9",
                "facilities": [
                    {
                        "facility_code": "34124",
                        "facility_name": "Supremax city center",
                        "zones": [
                            {
                                "zone_code": "15124",
                                "zone_name": "Upper level",
                            }
                        ]
                    }
                ]
            }
        ]
    }
    
    

Create a new tenant

Creates a new tenant and returns the new tenant's ID. Even though the tenant ID is returned, it might take a couple of seconds for the tenant to be created in all subsystems. Using the newly created tenant ID in a subsequent request might lead to an error in case the second request is sent in immediately after the first one. In such case the second request should be retried a few seconds later.

Endpoint

PUT https://api.autopay.io/permit/v2/landlord/{landlordId}/tenant/new

Request parameters:

  • The HTTP headers must include a valid access token.
  • The access token must include operator_id and landlord_id.
  • landlordId is the ID of the landlord under which the new tenant should be created.
Parameter Type Description
name string The name of the new tenant. This will be set both as tenant name & the display name for the tenant which is visible only for landlords.
manager_email string The email address of the new tenant's manager.
type enum Sets the type of the new tenant. The possible values are FULL and BASIC. Use FULL if the tenant is a company, or if they will receive more than one permit per allocation. Such tenants will have access to other functionality too in autopay.io - like booking and Tap & Park. BASIC tenant should be used in case the tenant is an individual, and should be receiving exactly one permit per allocation.

Example request:

    
    {
        "name": "My new tenant",
        "manager_email": "example@autopay.io",
        "type": "FULL"
    }
    
    

Success response:

HTTP Code: 200 OK

Parameter Type Description
tenant_id string The ID of the new tenant.

Get a tenant's existing permit allocations

This method returns all existing permit allocations that belong to the given tenant. The list includes all permit allocations, regardless of whether they were created via this API, or in autopay.io.

Endpoint

GET https://api.autopay.io/permit/v2/landlord/{landlordId}/tenant/{tenantId}

Request parameters:

  • The HTTP headers must include a valid access token.
  • The access token must include operator_id and landlord_id.
  • landlordId is the ID of the landlord which the tenant in question belongs to.
  • tenantId is the ID of the tenant for which this query should be run.

Success response:

HTTP Code: 200 OK

Parameter Type Description
name string The display name of the tenant, as set by the tenant manager(s)
tenant_id string The ID of the tenant to which the following permit allocations belong.
permit_allocations array The list of permit allocations that the tenant has access to.
updated_via_api boolean This field is true if the given allocation was created or has been updated via this API. Allocations that have been created directly in autopay.io (and have not been updated by this API) will have this flag set to false.
permit_allocation_id string The ID of the permit allocation.
permit_definition_id string The ID of the permit definition that this allocation was created with.
parking_spaces_count number The number of parking spaces that can be used simultaneously by the users of this permit allocation.
permit_count number The number of permits that the tenant is allowed to issue to end-users.
valid_from ISO date The day from which this permit allocation is valid.
valid_to ISO date The day until which this permit allocation is valid.
time_zone_id string The ID of the time zone where the validity dates should be interpreted

Example success response:

    
    {
        "name": "My tenant",
        "tenant_id": "8ejd8s-d935js-jfe34",
        "permit_allocations": [
            {
                "updated_via_api": true,
                "permit_allocation_id": "34512",
                "permit_definition_id": "93469",
                "parking_spaces_count": 10,
                "permit_count": 20,
                "valid_from": "2018-06-19",
                "valid_to": "2028-01-13",
                "time_zone_id": "Europe/Oslo"
            }
        ]
    }
    
    

Error responses

Code Explanation
409 Conflict The tenant that the query was run for is not fully created yet. This condition should not last more than a few seconds. Retry the request later.

Create a new permit allocation

Creates a new permit allocation on an existing tenant.

Endpoint

PUT https://api.autopay.io/permit/v2/landlord/{landlordId}/permitAllocations/new

Request parameters:

  • The HTTP headers must include a valid access token.
  • The access token must include operator_id and landlord_id.
  • landlordId is the ID of the landlord under which the new allocation should be created.
Parameter Type Description
tenant_id string The ID of the tenant for which the new allocation should be created.
permit_definition_id string The ID of the permit definition that this allocation should be created with.
parking_spaces_count number The number of parking spaces that can be used simultaneously by the users of this permit allocation. For basic tenants, this should be set to 1.
permit_count number The number of permits that the tenant is allowed to issue to end-users. For basic tenants, this should be set to 1.
valid_from ISO date The day from which this permit allocation is valid.
valid_to ISO date The day until which this permit allocation is valid. The latest date accepted is 2099-01-01, which means no end date.

Example request:

    
    {
        "tenant_id": "8ejd8s-d935js-jfe34",
        "permit_allocation": {
            "permit_definition_id": "93469",
            "parking_spaces_count": 10,
            "permit_count": 20,
            "valid_from": "2018-06-19",
            "valid_to": "2028-01-13"
        }
    }
    
    

Success response:

HTTP Code: 200 OK

Parameter Type Description
tenant_id string The ID of the tenant to which the following, new permit allocation belongs.
permit_allocation_id string The ID of the permit allocation.
parking_spaces_count number The number of parking spaces that can be used simultaneously by the users of this permit allocation.
permit_count number The number of permits that the tenant is allowed to issue to end-users.
valid_from ISO date The day from which this permit allocation is valid.
valid_to ISO date The day until which this permit allocation is valid.
time_zone_id string The ID of the time zone where the validity dates should be interpreted

Example success response:

    
    {
        "tenant_id": "8ejd8s-d935js-jfe34",
        "permit_allocation": {
            "permit_allocation_id": "34512",
            "parking_spaces_count": 10,
            "permit_count": 20,
            "valid_from": "2018-06-19",
            "valid_to": "2028-01-13",
            "time_zone_id": "Europe/Oslo"
        }
    }
    
    

Error responses

Code Explanation
409 Conflict The tenant that should be receiving the permit allocation is not fully created yet. This condition should not last more than a few seconds. Retry the request later.

Update permit allocation

Updates an existing permit allocation. If the allocation was originally created via autopay.io (and hence has the updated_via_api flag set to false), it will cause this flag to be set to true permanently. It might happen that the update cannot be applied as requested, e.g due to more permits being issued than the updated number of available permits. In this case the new number is going to be as close as possible to what was requested. The result of the update is returned in the response.

Endpoint

POST https://api.autopay.io/permit/v2/landlord/{landlordId}/tenant/{tenantId}/permitAllocations/{permitAllocationId}

Request parameters:

  • The HTTP headers must include a valid access token.
  • The access token must include operator_id and landlord_id.
  • landlordId is the ID of the landlord under which the allocation should be updated.
  • tenantId is the ID of the tenant under which the allocation should be updated.
  • permitAllocationId is the ID of allocation to be updated.
Parameter Type Description
parking_spaces_count number The number of parking spaces that can be used simultaneously by the users of this permit allocation. For basic tenants, this should be set to 1.
permit_count number The number of permits that the tenant is allowed to issue to end-users. For basic tenants, this should be set to 1.
valid_from ISO date The day from which this permit allocation is valid.
valid_to ISO date The day until which this permit allocation is valid. The latest date accepted is 2099-01-01, which means no end date.

Example request:

    
    {
        "parking_spaces_count": 10,
        "permit_count": 20,
        "valid_from": "2018-06-19",
        "valid_to": "2028-01-13"
    }
    
    

Success response:

HTTP Code: 200 OK

Parameter Type Description
tenant_id string The ID of the tenant to which the following permit allocation belongs.
permit_allocation_id string The ID of the permit allocation.
parking_spaces_count number The number of parking spaces that can be used simultaneously by the users of this permit allocation.
permit_count number The number of permits that the tenant is allowed to issue to end-users.
valid_from ISO date The day from which this permit allocation is valid.
valid_to ISO date The day until which this permit allocation is valid.
time_zone_id string The ID of the time zone where the validity dates should be interpreted

Example success response:

    
    {
        "tenant_id": "8ejd8s-d935js-jfe34",
        "permit_allocation": {
            "permit_allocation_id": "34512",
            "parking_spaces_count": 10,
            "permit_count": 20,
            "valid_from": "2018-06-19",
            "valid_to": "2028-01-13",
            "time_zone_id": "Europe/Oslo"
        }
    }
    
    

Delete permit allocation

Deletes an existing permit allocation.

Endpoint

DELETE https://api.autopay.io/permit/v2/landlord/{landlordId}/tenant/{tenantId}/permitAllocations/{permitAllocationId}

Request parameters:

  • The HTTP headers must include a valid access token.
  • The access token must include operator_id and landlord_id.
  • landlordId is the ID of the landlord under which the allocation should be deleted.
  • tenantId is the ID of the tenant under which the allocation should be deleted.
  • permitAllocationId is the ID of allocation to be deleted.

Success response:

HTTP Code: 200 OK

Permit Management

Migration guide from V1 to V2 (current version) and version differences

  • GET /tenant/permits
    • renamed request parameter product_id to permit_definition_id
    • renamed response parameter product_id to permit_definition_id
    • renamed response parameter product_name to permit_definition_name
  • POST /end_user_permit
    • renamed request parameter product_id to permit_definition_id
    • renamed response parameter product_id to permit_definition_id
    • renamed response parameter product_name to permit_definition_name
  • PUT /end_user_permit/{permitId}
    • renamed response parameter product_id to permit_definition_id
    • renamed response parameter product_name to permit_definition_name
  • GET /products
    • rename endpoint to /permit_definitions

Resource: 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/v2/permit_definitions

Request parameters:

Success response:

HTTP Code: 200 OK

Parameter Type Description
id integer ID of the permit allocation
name string Name of the permit allocation
description string Permit allocation description

Example success response:

    
    [
        {
            "id": 19,
            "name": "Parking zone 156 default permit allocation",
            "description": "Permit allocation description"
        }
    ]
    
    

Resource: 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/v2/tenant_permits

Request parameters:

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

Example request

GET https://api.autopay.io/permit/v2/tenant_permits?permit_definition_id=267

Success response:

HTTP Code: 200 OK

Parameter Type Description
permit_id integer 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_definition_id integer 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_date datetime (ISO 8601) Date when the permit was activated. Equal to permit created date if the customer had an autopay.io account.

Example success response:

    
    [
        {
            "permit_id": 2,
            "email": "lars@autopay.io",
            "permit_definition_id": 7,
            "permit_definition_name": "zone_1111_long_term_service_type",
            "valid_from": "2018-06-18T00:00:00Z",
            "valid_to": "2025-12-18T23:59:00Z",
            "activated": true,
            "activated_date": 2018-06-02T13:00:00Z
        }
    ]
    
    

Resource: POST

Give end user permit

Method to give permit to end user.

Endpoint

POST https://api.autopay.io/permit/v2/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_definition_id integer 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
valid_to date (YYYY-MM-DD) yes Date until which the permit is valid

Request example:

    
    {
        "permit_definition_id": 7,
        "email": "erik@autopay.io",
        "valid_from": "2018-06-19",
        "valid_to": "2025-12-19"
    }
    
    

Success response:

HTTP Code: 200 OK

Parameter Type Description
permit_id integer 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_definition_id integer 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_date datetime (ISO 8601) Date when the permit was activated. Equal to permit created date if the customer had an autopay.io account.

Example success response:

    
    {
        "permit_id": 74,
        "email": "erik@autopay.io",
        "permit_definition_id": 7,
        "permit_definition_name": "zone_1111_long_term_service_type",
        "valid_from": "2018-06-18T00:00:00Z",
        "valid_to": "2025-12-18T23:59:00Z",
        "activated": false,
        "activated_date": null
    }
    
    

Resource: PUT

Update end user permit

Method to update the validity period of the parking permit.

Endpoint

PUT https://api.autopay.io/permit/v2/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) yes Date from which the permit is valid
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"
    }
    
    

Success response:

HTTP Code: 200 OK

Parameter Type Description
permit_id integer 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_definition_id integer 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_date datetime (ISO 8601) Date when the permit was activated. Equal to permit created date if the customer had an autopay.io account.

Example success response:

    
    {
        "permit_id": 74,
        "email": "client_with_cc@autopay.test",
        "permit_definition_id": 7,
        "permit_definition_name": "zone_1111_long_term_service_type",
        "valid_from": "2018-06-18T00:00:00Z",
        "valid_to": "2025-12-18T23:59:00Z",
        "activated": false,
        "activated_date": null
    }
    
    

Resource: DELETE

Remove end user permit

Method to remove permit from end user.

Endpoint

DELETE https://api.autopay.io/permit/v2/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

Example success response:

    
    {
      "success": true,
    }
    
    

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
get_end_user_permit_list_error Error fetching end user permit list.
get_tenant_permits_operator_not_found_error Operator not found.
get_permit_definitions_error Error fetching permit definition list.
get_permit_definitions_operator_not_found_error Operator not found.
create_end_user_permit_error Error creating end user permit.
create_end_user_permit_operator_not_found_error Operator not found.
update_end_user_permit_error Error updating end user permit.
update_end_user_permit_operator_not_found_error Operator not found.
remove_end_user_permit_error Error updating end user permit.
remove_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