Permit E-commerce API

Access requirements:

• A valid authentication token is required to access the API. How to authenticate your application

Permit Management

The Permit E-commerce API can be used by landlords to issue permit allocations to tenants. The API supports creating, updating and deleting permit allocations as well as creating and querying tenants.

Available operations:

• GET - Get the available permit definitions
• PUT - Create a new tenant
• GET - Get a tenant's existing permit allocations
• PUT - Create a new permit allocation
• POST - Update permit allocation
• DELETE - Delete permit allocation
• Error handling

GET - 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

Example success response:

{
    "landlord_id": "1a6f4e3b-2db6-46ea-a095-a8c76c995596",
    "permit_definitions": [
        {
            "permit_definition_id": "37ae77b3-a66d-4bde-ba95-ae66f18f90a9",
            "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",
                        }
                    ]
                }
            ]
        }
    ]
}

PUT - 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.

Example request:

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

Success response:

HTTP Code: 200 OK

GET - 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

Example success response:

{
    "name": "My tenant",
    "tenant_id": "b8148a3c-591d-4fc5-9d29-d2917393ed1c",
    "permit_allocations": [
        {
            "updated_via_api": true,
            "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
            "permit_definition_id": "37ae77b3-a66d-4bde-ba95-ae66f18f90a9",
            "parking_spaces_count": 10,
            "permit_count": 20,
            "valid_from": "2018-06-19",
            "valid_to": "2028-01-13",
            "time_zone_id": "Europe/Oslo"
        }
    ]
}

Error responses

PUT - 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.

Example request:

{
    "tenant_id": "b8148a3c-591d-4fc5-9d29-d2917393ed1c",
    "permit_allocation": {
        "permit_definition_id": "37ae77b3-a66d-4bde-ba95-ae66f18f90a9",
        "parking_spaces_count": 10,
        "permit_count": 20,
        "valid_from": "2018-06-19",
        "valid_to": "2028-01-13"
    }
}

Success response:

HTTP Code: 200 OK

Example success response:

{
    "tenant_id": "b8148a3c-591d-4fc5-9d29-d2917393ed1c",
    "permit_allocation": {
        "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
        "parking_spaces_count": 10,
        "permit_count": 20,
        "valid_from": "2018-06-19",
        "valid_to": "2028-01-13",
        "time_zone_id": "Europe/Oslo"
    }
}

Error responses

POST - 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.

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

Example success response:

{
    "tenant_id": "b8148a3c-591d-4fc5-9d29-d2917393ed1c",
    "permit_allocation": {
        "permit_allocation_id": "f8ab6b8b-3b20-419a-9381-aec7d76ec2a6",
        "parking_spaces_count": 10,
        "permit_count": 20,
        "valid_from": "2018-06-19",
        "valid_to": "2028-01-13",
        "time_zone_id": "Europe/Oslo"
    }
}

DELETE - 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

Error messages

Example error response:

{
    "error_id": "authentication_error",
    "message": "No access token present in header!"
}

Possible error ID-s: