Introduction

Welcome to the documentation and reference page of the EVVA AirKey Cloud API. Our REST-API provides the customer with powerful control of his AirKey infrastructure from any third-party application.

Features

These features can be controled via API:

  • Manage persons
  • Manage smartphones and other access media like cards, key tags, etc.
  • Assign smartphones or other access media to persons
  • Authorize smartphones or other access media to access locking components (locks) or areas at given times
  • Access protocols
  • Additional administration for blacklists, credits, holiday calendars, and maintenance tasks

Some components of AirKey cannot be controlled through the API, as they have no internet connection. This concerns mostly parts which are set up only once:

  • Registering new locks and their assignment to areas
  • Adding new RFID access media like cards and key tags
  • Administrative settings as buying credits or requesting API keys

API Activation

You need to generate a secret API key to access the API. The key is sent trough a HTTP header (X-API-Key) every time you access the API. Beside the production API, we provide a test environment for development purposes. Here you can try out all API features in a safe sandbox-like environment.

To activate the API open https://airkey.evva.com in your web browser. Go trough the "AirKey registration" process if you haven’t registered yet. Then log in and choose "Settings".

Test API

The test environment is free of charge. A predefined set of test data can be loaded and reset to the intial state anytime.
Please note that it is not possible to access the test environment’s data in the AirKey online administration. Furthermore no real SMS text messages will be sent in the test environment.

To activate the test API go to "Settings" → "AirKey Cloud Interface (API) – test environment" and select "Generate API-key". Immediately write down the API key, as it is displayed only once for security reasons.
You can reset the provided test data to the predefined data set anytime by clicking on "Reset test data", or by sending the "/v1/public-mgmt/reset-test-data" request via the API.

Production API

To activate the actual production API click the "Activate API" button (350 credits needed). After the activation you can generate your secret API key. The key is displayed only once. Use this key instead of the test API key to switch from testing to production operation.

Attention, you are now working with real production data!

In case of problems, please try to repoduce them in the test environment before contacting support.

Connecting to the API

There are several ways in which you can access the EVVA AirKey Cloud API:

Manually

The easiest way to perform requests is by using the built in "Try it out" feature of the Swagger Documentation below. First click on "Authorize" and enter your API key. Then you can use the "Try it out" button next to each request.

Another convenient option is to use a tool like Postman.

From your application

To access AirKey directly from your application you have two main options: You can simply send direct request with tools like "curl" and handle the requests yourself, or you can use generated classes for your programming language via the Swagger Generator.

Here is a short rundown of how to use Swagger Generator:

  • Go to https://generator.swagger.io
  • Click on "clients" → "POST /gen/clients/{language}"
  • Click on "Try it out"
  • Select the programming language of choice
  • Set the "body" field as follows:
    {
        "spec": {},
        "options": {},
        "swaggerUrl": "https://integration.api.airkey.evva.com/docs/swagger.json"
    }
    
  • Then click the blue "Execute" button
  • You can now download the generated lib at the URL given in den "Response body"

Please note that EVVA cannot provide any implementation support for the API. Contact your software development, agency or vendor for support.

How to use the API

In the following we provide some general information about the usage of the API:

Swagger Documentation

Below you can find the extensive Swagger Documentation for all request types and models (objects). Information about the request URLs, query parameters, request body configuration, examples of body and response, as well as valid response codes are provided there.

For body and response you can click on the "Model" link to get information about the fields. Provided are details about data type, required (marked by a red asterix) and read only. Note that you can expand child models by clicking on them.
Example: GET /persons → Responses → Model → personList (click on the right angle bracket) → Person → correspondenceLanguageCode (click on the right angle bracket)

Authorization header "X-API-Key"

For each request a valid API key must be sent in the HTTP header (name "X-API-Key"). To generate a new API key, see section "API Activation".

Data format JSON

JSON notation is used throughout the API.

  • Responses are returned as JSON
  • PUT and POST request bodies expect JSON
  • DELETE requests take a JSON array of object IDs

URL encoding

Make sure to properly apply URL encoding for query parameters according to RFC 3986.

Paging

Most GET requests use paging. Per default 20 entries are returned. You can retrieve up to 100 entries by giving the "limit" query parameter.

Example: /persons?limit=100

Subsequent pages are loaded via the "offset" query parameter.

Example to load page two: /persons?limit=10&offset=2

Workflow of updating objects and versioning

If you want to update an existing object you should retrieve it first via "GET" request, modify the values as you wish, and then perform a "PUT" request.

The reason for that is that many PUT requests require to add the current version of the object. This is important to avoid concurrent modifications and overrides.

Please note that you have to give all required fields, even if they are read only.

Language and country codes

Currently supported:
  • 11 language codes (ISO 639-1 compliant and case sensitive):
    cs-CZ, de-DE, en-UK, es-ES, fr-FR, it-IT, nl-NL, pl-PL, pt-PT, sk-SK, sv-SE

  • 250 country codes (ISO 3166-1 alpha-3 compliant and case sensitive):
    ABW, AFG, AGO, AIA, ALA, ALB, AND, ANT, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CHN, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRA, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SCG, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE

Dates and times

Timestamps are generally provided in ISO 8601 date and time format, with time in UTC and millisecond precision. The UTC timezone is defined by the "Z" in last position. Seconds and milliseconds are optionally.

Example: 2019-05-09T09:25:36.608Z

Date fields which hold only the date without time follow a naming convention with "Date" suffix.
Example: "validFrom" (date + time) vs. "validFromDate (only date)

Dates and times for authorizations

Attention: Timestamps for authorizations are given without timezone (without "Z" character in last position), because locking components work in the local timezone and need times relative to their time zone. For example you want to provide access to a door at 4:00 p.m. in the time zone of the locking component, and not at 4:00 p.m. UTC.

Example: 2019-05-09T09:30    /* without "Z" character */

Furthermore authorization timestamps take only certain minute values and no seconds or milliseconds.
Valid minute values for authorization: 00, 05, 10, 15, 20, 30, 40, 45, 50, 55

ID vs. Identifier

The API uses the following naming convention regarding IDs:

  • ...Id is the native database ID (e.g. lockId=140023087)
    Most of the time you will use these native database IDs when working with the API.
  • ...Identifier is the component identifier used in the AirKey online administration for access media and locking components (e.g. lockIdentifier=000000000858E6D0)

HTML code formatting for protocol entries

The translation fields for protocol responses contain various CSS class definitions. The necessary files for human friendly representation for these fields are:

Workflow Example: Authorization

In this section we’ll give you a short introduction of a common authorization life cycle.
You can also try out and inspect these requests in our API Demo App.

Create authorization for smartphone

The simplest way to create an authorization for a smartphone is to use the convenient "/send-a-key" request. This is a single simplified interface for multiple requests in the background: create a person, create a "phone" medium, assign the medium to the person and create an authorization for the phone to the given locking component and time.

Update

To update data from the previous "/send-a-key" request you need to perform separate update requests for the involved data models:

  • To modify personal data (firstName, ...) you need to "GET" the person via "/persons/{personId}" and then "PUT" the modified JSON object.
  • To modify data of the medium (mobileNumber, ...) you need to "GET" the medium via "/media/{mediaId}" and then "PUT" the modified JSON object.
  • Authorizations are very powerful in AirKey and thus a bit more complex.
    If you simply want to replace all existing authorizations created by "send-a-key" you can do the following:
    POST /authorizations/simple
    {
         "authorizationInfo": {
             "type": "SIMPLE",
             "validFrom": "2019-05-15T09:50",
             "validTo": "2019-06-21T09:00"
         },
         "mediumId": 253,
         "lockId": 140023087,
         "removeAllExistingAuthorizationsForPair": true
    }
    
    Explanation: We create an authorization of type "SIMPLE" which takes only "validFrom" and "validTo" timestamps, and the IDs of medium and locking component. Additionally we give the option "removeAllExistingAuthorizationsForPair" which replaces all existing authorizations for this medium - locking component pair with the new authorization.

Delete

If you want to delete all data created by a "/send-a-key" request you have to perform the following steps in the correct order:

  • POST /media/{mediumId}/empty
    Removes all authorizations from a medium.
  • POST /media/cancel-assignment
    Takes the {mediumId} as body and unassigns the medium from the person.
  • DELETE /media/phones
    Takes {mediumId} as body and removes the phone entry.
  • DELETE /persons
    Takes {personId} as body and removes the person entry.

Additional Information

A lot of additional information can be found in the AirKey System Manual.

Please contact your EVVA partner for AirKey support inqueries.

Changelog

v12.60.7

  • The request "PUT /locks" now also saves the comment field.
  • Improved description for "simpleAuthorization" in documentation.
  • Renamed authorization date fields (without time) to "validFromDate" and "validToDate" for the types "ONE_DAY" and "PERIODICAL".
  • Added fields "fax" and "contactTitle" to the "GET /customer" request.
  • Removed redundant requests "GET /areas/protocol" and "GET /locks/protocol". These requests are now handled by the "GET /lock-protocol" request with a corresponding parameter ("areaId" respectively "lockId").
  • All requests use now the plural of "slot": "GET /holidayCalendars/.../slots/", etc.