Intercom service

Description

The Intercom service API showcases the different ways to configure and manage the core functionality of the intercom devices.

Model

The intercom service provides the API endpoint /vapix/intercom as well as the websockets endpoints ws:// and wss:// at /vapix/intercomws. The websocket endpoint can be used to both issue API commands and to initiate event notifications in the JSON format.

The intercom service includes the following methods:

Configure the access control integration protocol to request access to any compatible device. This can be done by using either OSDP, Wiegand or VAPIX reader connection.
Enabling card types.
Allowing third-party integrators to configure and control card data processing using the access control integration protocol.
Configuring the user interface behavior and API to control the feedback.

The intercom service also defines a number of events for real-time monitoring:

Card swipe events using tns1:Device/tnsaxis:Intercom/RFID
PIN entry events using tns1:Device/tnsaxis:Intercom/KeyPin
Aggregated call state events.

Non normative enums are used to describe possible values and their meaning, together with capabilities listing the supported values on a particular product or firmware.

Identification

Property: Properties.API.Intercom.Intercom="yes"
Property: Properties.API.Intercom.Version="1.1"
API Discovery: id=intercom-api
API Discovery: id=intercom-reader (for products with a reader)

Terminology

Term	Description
AccessPoint	Represents a reader or reader-door mapping.
ACU	Access Control Unit, i.e. external access control device or door controller, such as AXIS A1001 and AXIS A1601.
RFID	Radio Frequency IDentification. The radio technology used in cards, tags and fobs for identification.
Mask	Used together with readers to disable/filter data from being used with the configured access control integration protocol.
MIFARE®	A brand named RFID-based solution for storing credential information on smart cards and keyfobs (RFC tags).
MIFARE® DESFire®	A brand named RFID-based solution for storing credential information on smart cards and keyfobs (RFC tags).
Non-normative Enum	An Enum whose values are used as strings to enable future extensions. The type documents the possible values and their meaning, but a capability indicates the supported values, and an ID string type is used instead of the actual enum type when appropriate.
OSDP	Open Supervised Device Protocol. A protocol on top of a 2–wire RS-485 used between the access control system (ACU) and a reader.
PIN	Personal Identification Number. The number used to authenticate a user, commonly used with an RFID card.
Tag	Another term for a smartcard or keyfob used to store credential information.
Wiegand	A protocol widely used in access control systems between a reader and controller (ACU).

Common examples

Syntax

API calls can be encoded in either JSON or as a key-value format referred to as “simple”. Multiple JSON formats are supported, such as JSONRPC 2.0 and Google JSON API.

JSON

The original JSON format has the following form:

Request ver. 1

{
  "<function>": {
    <arguments>
  }
}

This JSON request can also be made by putting the function-method in the URL: /vapix/intercom/<function>:

Request ver. 2

{
  <arguments>
}

Response

{
  <result>
}

JSONRPC 2.0

The JSONRPC 2.0 format has the following form:

Request

{
  "jsonrpc": "2.0",
  "method": <function>,
  "params": {
    <arguments>
  },
  "id": <id>
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    <result>
  },
  "id": <id>
}

Google JSON API

The Google JSON API has a similar structure to JSONRPC 2.0, but uses different parameters.

Request

{
  "apiVersion": "1.0",
  "method": "<function>",
  "params": {
    <arguments>
  },
  "context": <id>
}

Response

{
  "apiVersion": "1.0",
  "data": {
    <result>
  },
  "context": <id>
}

Simple

The so called “simple” format flattens the structure to key=value strings, where each level in a structure is separated by an underscore _ when encoding the key.

Boolean values are encoded as either true or false, while the NULL value is encoded as null.
String values are URL-encoded and may start and end with quotation marks.
Array keys are encoded as _index_ starting from 0.

Character sets are neither converted nor validated by the intercom service, but UTF-8 should be used to ensure compatibility with most system.

Simple cURL example

This example shows a couple of configurations requested via cURL.

cURL JSON

Request

$ curl --digest "//root:pass@192.168.0.90/vapix/intercom" -s
  -d'{"GetConfiguration":{}}'
{
  "Configuration": {
    "Version": "1.0",
    "CallTriggersEnabled": true,
    "CallByNumbersEnabled": true,
    "DefaultCallByNumberSIPAccountId": "",
    "CardReaderConfiguration": {
      "Protocol": "None",
      "CardTypes": [ "MIFARE_Classic",.. ],
      "WiegandConfiguration": {
        "nbrOfLEDPins": 0,
        "beeper": false,
        "beeperPin": "I3",
        "LED1Pin": "I1",
        "LED2Pin": "I2",
        "LEDColor0": "red",
        "LEDColor1": "green",
        "LEDColor00": "off",
        "LEDColor01": "green",
        "LEDColor10": "red",
        "LEDColor11": "amber",
        "keypressFormat": "FourBit"
      },
      "OSDPConfiguration": {
        "OSDPAddress": 0
      }
    }
  }
}

cURL Simple

Request

$ curl --digest "//root:pass@192.168.0.90/vapix/intercom?format=simple&action=GetConfiguration"
or
$ curl --digest "//root:pass@192.168.0.90/vapix/intercom/GetConfiguration?format=simple"

Configuration_Version="1.0"
Configuration_CallTriggersEnabled=true
Configuration_CallByNumbersEnabled=true
Configuration_CardReaderConfiguration_Protocol="None"
Configuration_CardReaderConfiguration_CardTypes_0="EM4X02"
Configuration_CardReaderConfiguration_CardTypes_1="HITAG_1_S"
Configuration_CardReaderConfiguration_CardTypes_2="HITAG_2"
Configuration_CardReaderConfiguration_CardTypes_3="EM4X50"
Configuration_CardReaderConfiguration_CardTypes_4="ISOFDX_B"
Configuration_CardReaderConfiguration_CardTypes_5="HID_PROX"
Configuration_CardReaderConfiguration_CardTypes_6="AWID"
Configuration_CardReaderConfiguration_CardTypes_7="MIFARE_Classic"
Configuration_CardReaderConfiguration_CardTypes_8="ISO15693"
Configuration_CardReaderConfiguration_CardTypes_9="HID_ICLASS"
Configuration_CardReaderConfiguration_WiegandConfiguration_nbrOfLEDPins=0
Configuration_CardReaderConfiguration_WiegandConfiguration_beeper=false
Configuration_CardReaderConfiguration_WiegandConfiguration_beeperPin="I3"
Configuration_CardReaderConfiguration_WiegandConfiguration_LED1Pin="I1"
Configuration_CardReaderConfiguration_WiegandConfiguration_LED2Pin="I2"
Configuration_CardReaderConfiguration_WiegandConfiguration_LEDColor0="red"
Configuration_CardReaderConfiguration_WiegandConfiguration_LEDColor1="green"
Configuration_CardReaderConfiguration_WiegandConfiguration_LEDColor00="off"
Configuration_CardReaderConfiguration_WiegandConfiguration_LEDColor01="green"
Configuration_CardReaderConfiguration_WiegandConfiguration_LEDColor10="red"
Configuration_CardReaderConfiguration_WiegandConfiguration_LEDColor11="amber"
Configuration_CardReaderConfiguration_WiegandConfiguration_keypressFormat="FourBit"
Configuration_CardReaderConfiguration_OSDPConfiguration_OSDPAddress=0
...

Errors

A faulty request, such as missing required information or containing parameters the service doesn’t recognize will always return an error response, typically done with an HTTP 400 Bad request code unless the fault was over a websocket connection.

The error response also contains additional information. Typical FaultCodes for this API might be ter:TagMismatch, ter:InvalidArgval or ter:InvalidArgs.

TagMismatch error

{
  "Fault": env:Sender",
  "FaultCode": "ter:TagMismatch",
  FaultSubCode": null,
  "FaultReason": "Tag mismatch",
  "FaultMsg": "JSON parse error: axdsapi:CardReaderConfiguration - Unhandled field: 'WrongField' at pos 66 {WrongField..}"
}

Simple format error

Fault="env:Sender"
FaultCode="ter:TagMismatch"
FaultSubCode=null
FaultReason="Tag mismatch"
FaultMsg="JSON parse error: axdsapi:CardReaderConfiguration - Unhandled field: 'WrongField' at pos 66 {WrongField..}"

JSON formatted InvalidArgVal error

{
  "Fault": "env:Sender",
  "FaultCode": "ter:InvalidArgVal",
  "FaultSubCode": null,
  "FaultReason": "Invalid argument",
  "FaultMsg": "BeeperVolume should be <=100"
}

Google JSON formatted InvalidArgVal error

{
  "apiVersion": "1.0",
  "context": "context1602748757.259225",
  "error": {
    "code": -32700,
    "message": "BeeperVolume should be <=100",
    "errors": [
      {
        "domain": "env:Sender",
        "reason": "Invalid argument",
        "message": "BeeperVolume should be <=100",
        "location": "ter:InvalidArgVal"
      }
    ]
  }
}

JSONRPC2.0 formatted InvalidArgVal error

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32700,
    "message": "BeeperVolume should be <=100,
    "data": {
      "Fault": "env:Sender",
      FaultCode": "ter:InvalidArgVal",
      "FaultSubCode": null,
      "FaultReason": "Invalid argument",
      "FaultMsg": "BeeperVolume should be <=100"
    }
  }
  "id": "id1602750260"
}

Configure reader integration protocols

Use this example to build the RFID reader together with an external Access control system. Please note that you need to configure which protocol to use if the controller doesn’t connect to the device and subscribes to integration events on its own.

The following code showcase two different ways to configure the OSDP reader integration protocol:

{
  get_response = intercom.GetConfiguration()
  config = get_response['CardReaderConfiguration']
  config['Protocol'] = 'OSDP'
  intercom.UpdateConfiguration(CardReaderConfiguration=config)
}

{
  "UpdateConfiguration": {
    "Configuration": {
      "CardReaderConfiguration": {
        "Protocol": "OSDP"
      }
    }
  }
}

Configure card types

Use this example to configure the card types by setting the CardTypes list in the CardReaderConfiguration. This should contain the desired card formats. Card formats not used by a site should be disabled, both from a security and performance perspective.

To find out what Card types that are supported on your device, you need to check GetSupportedTagTypes or GetServiceCapabilities.

The following code is used to check for supported cards and configure the Card types:

{
  supported_cards = intercom.GetSupportedTagTypes()
  config = intercom.GetConfiguration()
  enablecards = config.CardReaderConfiguration.CardTypes

  // Remove all LowFrequency cards from enabledcards list:
  for cardtype in supported_cards {
    if (cardtype.Category == 'LowFrequency') {
      enabledcards.remove(cardtype.Name)
    }
  }
  // Set the modified list of enabled CardTypes
  config.CardReaderConfiguration.CardTypes = enabledcards
  intercom.UpdateConfiguration(config)
}

The following codes showcases how you can change the card types. Both uses the UpdateConfiguration method, while the second one also includes the use of an URL:

POST to/vapix/intercom
{
  "UpdateConfiguration": {
    "Configuration": {
      "CardReaderConfiguration": {
        "CardTypes": ["MIFARE_Classic"]
      }
    }
  }
}

POST to /vapix/intercom/UpdateConfiguration
{
  "Configuration": {
    "CardReaderConfiguration": {
      "CardTypes": ["MIFARE_Classic"]
    }
  }
}

Configure PIN setting

Use this example to change the Pin settings and timeout. To do this, you need to call the UpdateConfiguration method and include the fields you wish to modify.

Configure the PIN settings

{
// Start with an empty config object:
  config = {}
  config.CardReaderConfiguration = {}
  config.CardReaderConfiguration.PinConfiguration = {}
// Only update these fields:
  config.CardReaderConfiguration.PinConfiguration.pinLength = 6
  config.CardReaderConfiguration.PinConfiguration.pinTimeout = 20
  intercom.UpdateConfiguration(config)
}

Change the timeout

{
  "UpdateConfiguration": {
    "Configuration": {
      "CardReaderConfiguration": {
        "PinConfiguration": {
          "pinLength": 6,
          "pinTimeout": 20
        }
      }
    }
  }
}

Third party integration

Use this example to configure your device so that a third party application can validate a card swipe before the card data gets sent over a configured reader protocol.

This involves:

Configuring the device to mask the internal reader. This is done by issuing a UpdateConfiguration or RegisterReader call.
Subscribing to the RFID events.
Calling the InjectTag, InjectKeySequence and SetUiFeedback methods.

The following code showcases how to validate the RFID data before sending it to a controller:

setup()
  {
    if (fixed) {
      config = {}
      config.CardReaderConfiguration.RegisteredReaderConfiguration.ReaderIds = ["ADP"]
      config.CardReaderConfiguration.RegisteredReaderConfiguration.Policy = "Fixed"
      intercom.UpdateConfiguration(config)
    }
    else
    {
      Timeout = intercom.RegisterReader(Readerid="ADP", DisableInternalReader = true, UnmaskIfLost = false)
    }
    // Subscribe to events, using RTSP metadata streaming, ONVIF PullPoint subscription or events in JSON over websocket: Using websocket endpoint /vapix/intercomws:

    device.websocket.connect("/vapix/intercomws")
    // Subscribe to event topics and functions: Send axev:subscribe with style = "ttMessage", topics=["Device/Intercom/RFID", "Device/Intercom/KeyPin"], functions = ["axev:notify", "axdsapi:SetUiFeedback"]
    device.websocket.send('{
      "apiVersion": "1.0",
      "method": "axev:subscribe",
      "params": {
        "style": "ttMessage",
        "functions": [
          "axev:notify",
          "axdsapi:SetUiFeedback"
        ],
        "topics": ["Device\/Intercom\/RFID", "Device\/Intercom\/KeyPin"]
      },
      "id": "firstsubscribe"
    }')
    device.websocket.on_message_handler = handle_websocket_message
  }

  handle_websocket_message(json_msg)
  {
    msg = json2object(json_msg)
    if (msg.method == 'axev:notify')
    {
      for notification in msg.params.notifications {
        if (notification.topic == "tns1:Device/tnsaxis:Intercom/RFID") {
        // Only process if Source with name Source is Internal
        source = SimpleItem_lookup(notification.data.Data.SimpleItem, "Source")
        if (source == "Internal") {
          UID = SimpleItem_lookup(notification.data.Data.SimpleItem, "UID") 
          // Take snapshot, lookup UID on own database or whatever is needed
          result = partner_validation(UID)
          // result is expected to contain a combination of InjectTag, InjectKey and feedback
          if (result.injecttag) {
            // Card is valid, call InjectTag, based on the notification, possibly with a prefix

            BitCount = SimpleItem_lookup (notification.data.Data.SimpleItem, "BitCount")
            // Possibly prefix the UID with additional hex data, e.g. 0xFACE
            if (result.prefix !="") {
              UID = result.prefix + UID
              BitCount = BitCount + strlen(result.prefix)*4
            }
            send_InjectTag("ADP", UID, BitCount)
          }
          if (result.injectkey !='') {
            // Injectkey should end with # to make it a PIN code, or C to issue a call
            send _InjectKeySequence ("ADP", result.injectkey)
          }
          if (result.feedback) {
            //Send some feedback, e.g. 'AccessDenied'
            send_feedback(result.feedback)
          }
        }
      }
    }
  }
}

send_InjectTag(external_readerid, UID, BitCount)
{
  device.websocket.send('{
    "apiVersion": "1.0",
    "method": "InjectTag",
    "params": {
      "Tag": {
        "TagUid": "' + UID + '",
        "BitCount": ' + BitCount + ",
        "ReaderId": "' + external_readerid + '"
      }
    },
    "id": "clientInjectTag"
  }')
}

send_InjectKeySequence(source, keys)
{
  device.websocket.send('{
    "apiVersion": "1.0",
    "method": "InjectKeySequence",
    "params": {
      "KeySequence": "' + keys + '",
      "Source": "' + source + '"
    },
    "id": "clientInjectKeySequence"
  }')
}

send_feedback(feedback)
{
  device.websocket.send('{
    "apiVersion": "1.0",
    "method": "SetUiFeedback",
    "params": {
      "highlevelFeedbacks": ['+feedback+']
    },
    "id": "clientSetUiFeedback"
  }')
}

By using UpdateConfiguration, you will be able to change RegisteredReaderConfiguration with Google JSON:

POST to /vapix/intercom (or send to ws://ip/vapix/intercomws
{
  "apiVersion": "1.0",
  "method": "UpdateConfiguration",
  "params": {
    "Configuration": {
      "CardReaderConfiguration": {
        "RegisteredReaderConfiguration": {
          "ReaderIds": ["ADP"],
          "Policy": "Fixed"
        }
      }
    }
  },
  "context": "updateRegisteredReaderConfig"
}

By using this code, you will be able to use the RFID event notification over a websocket:

{
  "apiVersion": "1.0",
  "method": "axev:notify",
  "params": {
    "notifications": [
      {
        "topic": "tns1:Device\/tnsaxis:Intercom\/RFID",
        "timestamp": "2020-10-04T11:30:08.885643Z",
        "data": {
          "Source": { 
            "SimpleItem": [
              {
                "Name": "Source", "Value": "Internal"
              }
            ]
          },
          "Data": {
            "SimpleItem": [
              {
                "Name": "UIDFormat", "Value": "Raw"
              },
              {
                "Name": "TagType", "Value": "MIFARE_Classic"
              },
              {
                "Name": "BitCount", "Value": "32"
              },
              {
                "Name": "UID", "Value": "C0DE1234"
              }
            ]
          }
        }
      }
    ]
  }
}

API specifications

Common data types

Identifies a structure.

Base type: String (maxLength=64, minLength=0)

Name

The type used for names of logical and/or physical entities.

Base type: String (maxLength=64, minLength=0)

Attribute

An attribute containing a name and a value.

{
  "Name": "string",
  "Value": "string"
}

Field	Type	Description
`Name`	String	The attribute name.
`Value`	String	The value of the attribute.

AttributeInfo

Contains the attribute description.

{
  "Name": "string",
  "Value": "string",
  "Type": "string"
}

Field	Type	Description
`Name`	String	The attribute name.
`Value`	String	The attribute value.
`Type`	String	The attribute type (boolean, integer, string)

Card reader specific types

CardType

This chapter describes the different card types. See Service capabilities for a complete list of cards supported by the products.

{
  "Name": "MIFARE_Classic",
  "DisplayName": "MIFARE Classic",
  "Category": "HighFrequency",
  "DataSources": ["CSN",...]
}

Field	Type	Description
`Name`	Id	The card type identifier. See CardTypeNames for possible values.
`DisplayName`	Id	The UI-friendly name.
`Category`	Id	The category. See CardTypeCategory for possible values.
`DataSources`	Id array	The list of data sources that are supported. See CardDataSources for possible values.

CardTypeCategory

Value	Description
`HighFrequency`	13.56 MHz card type
`LowFrequency`	125 kHz card type

CardTypeNames

Value	Description
`EM4X02`	EM4x02
`HITAG_1_S`	HITAG 1/HITAG S
`HITAG_2`	HITAG 2
`EM4X50`	EM4x50
`T55X7`	T55x7
`ISOFDX_B`	ISO FDX-B
`EM4026`	EM4026
`HITAG_U`	HITAG U
`EM4305`	EM4305
`HID_PROX`	HID Prox
`ISOHDX_TIRIS`	ISO HDX TIRIS
`COTAG`	Cotag
`IOPROX`	ioProx
`INDALA`	Indala
`NEXWATCH`	NexWatch
`AWID`	AWID
`GPROX`	G-Prox
`PYRAMID`	Pyramid
`KERI`	Keri
`DEISTER`	Deister
`CARDAX`	Cardax
`NEDAP`	Nedap
`PAC`	PAC
`IDTECK`	IDTECK
`ULTRAPROX`	ULTRAPROX
`ICT`	ICT
`ISONAS`	ISONAS
`MIFARE`	Generic MIFARE®
`MIFARE_Classic`	MIFARE Classic®
`MIFARE_DESFire`	MIFARE® DESFire®
`MIFARE_Plus`	MIFARE Plus®
`MIFARE_Ultralight`	MIFARE Ultralight®
`ISO14443B`	ISO 14443–B
`ISO15693`	ISO 15693
`LEGIC`	LEGIC
`HID_ICLASS`	HID iClass
`FELICA`	FeliCa
`SRX`	SRX
`NFC_P2P`	NFC P2P
`BLE`	Bluetooth Low Energy
`TOPAZ`	TOPAZ
`CTS`	CTS

KeypressOutputFormat

This chapter showcases how the PIN is formatted when it is sent to the access control.

Value	Description
`FourBit`	PIN “1234” becomes 0x1 0x2 0x3 0x4 on the wire.
`EightBitZeroPadded`	PIN “1234” becomes 0x01 0x02 0x03 0x04 on the wire.
`EightBitInvertPadded`	PIN “1234” becomes 0xE1 0xD2 0xC3 0xB4 on the wire.
`Wiegand26`	PIN is encoded in a Wiegand26 format with an 8 bit facility code and a 16 bit id.
`Wiegand34`	PIN is encoded in a Wiegand34 format with a 16 bit facility code and a 16 bit id.
`Wiegand37`	PIN is encoded in a Wiegand37 format (H10302) with a 35 bit data.
`Wiegand37FacilityCode`	PIN is encoded in a Wiegand34 format (H10304) with a 16 bit facility code and a 19 bit id.

CardOutputFormat

This chapter showcases how card data is formatted when it is sent to the access control.

Value	Description
`Raw`	The card data is transmitted as it is.
`Wiegand26`	The card data is encoded in a Wiegand26 format with an 8 bit facility code and a 16 bit id.
`Wiegand34`	The card data is encoded in a Wiegand34 format with a 16 bit facility code and a 16 bit id.
`Wiegand37`	The card data is encoded in a Wiegand37 format (H10302) with a 35 bit data.
`Wiegand37FacilityCode`	The card data is encoded in a Wiegand37 format (H10304) with a 16 bit facility code and a 19 bit id.
`Custom`	Use the `OutputFormatConfiguration` option as described in CustomOutputFormatConfiguration.

FacilityCodeOverrideMode

This chapter describes the different behaviors of overriding the facility code.

Value	Description
`Auto`	Overrides will not be performed and creates a facility code from the input data auto detection: Either use the card’s original facility code or forge it from excess bits of a card number. This is the default option.
`Optional`	Uses the facility code from the input data, otherwise overrides with a configured value (optional).
`Override`	Always overrides with a specified `FacilityCode`.

ParityType

This chapter specifies the parity bit types.

Value	Description
`None`	Parity bit does not exist.
`Even`	The parity bit is even.
`Odd`	The parity bit is odd.
`Fix0`	The parity bit is always zero.
`Fix1`	The parity bit is always one.

CustomOutputFormatConfiguration

This chapter showcases the custom parameters for when the cardFormat is “Custom”. This part defines the format if no other value in the CardOutputFormat can be used.

{
  "facilityCodeSize": 8,
  "cardNumberSize": 16,
  "startParity": "Even",
  "startParityBits": 12,
  "stopParity": "Odd",
  "stopParityBits": 12
}

Field	Type	Description
`facilityCodeSize`	Integer	The size of the facility code.
`cardNumberSize`	Integer	The size of the card number.
`startParity`	Id	Default value is `None`.
`startParityBits`	Integer	Shows the number of data bits that are calculated in the start parity, counted from the first bit.
`stopParity`	Id	Default value is `None`.
`stopParityBits`	Integer	Shows the number of data bits calculated in the stop parity, counted backwards from the last bit.

OutputFormatConfiguration

This chapter specifies how the card data is configured and sent to the output.

{
  "cardFormat": "Raw",
  "cardFacilityCodeOverrideMode": "Auto",
  "cardFacilityCode": 0,
  "Custom": {
    CustomOutputFormatConfiguration
  }
}

Field	Type	Descripion
`cardFormat`	Id	How the card data is formatted. See CardOutputFormat for potential values and for supported values. The default value is `Raw`, which means that all fields that follows after this one is disregarded.
`cardFacilityCodeOverrideMode`	Id	See FacilityCodeOverrideMode for supported values (default value is `Auto`).
`cardFacilityCode`	Integer	The facility code to override the card in cases where the override mode is set to either Optional or Override. The maximum value depends on the card format that was selected: 255 for Wiegand26 (8 bits), 65535 for Wiegand34 and Wiegand37FacilityCode (16 bits).
`Custom`	See CustomOutputFormatConfiguration	The custom parameters in cases were `cardFormat` is `Custom`.

IOPinName

This chapter shows the names for the general IO pins.

Value	Description
`I1`	I/O 1
`I2`	I/O 2
`I3`	I/O 3
`I4`	I/O 4

AccesscontrolIntegrationProtocol

This chapter goes over the different ways that the device can communicate with an access control system.

Value	Description
`None`	No protocol selected.
`IPAccess`	VAPIX Reader over IP, see IPIntegrationProtocol for more information.
`OSDP`	OSDP over RS485.
`Wiegand`	Wiegand.

ColorName

This chapter presents the string of colors that may be supported on your device.

Value	Description
`off`	Off
`red`	Red
`green`	Green
`blue`	Blue
`amber`	Amber
`cyan`	Cyan
`magenta`	Magenta
`white`	White

WiegandConfiguration

This chapter goes over the configuration used for the Wiegand output to change the LED and beeper. All fields are optional and will keep their existing value if nothing is set.

{
  "nbrOfLEDPins": 3,
  "beeper": true,
  "beeperPin": "I1",
  "LED1Pin": "I2",
  "LED2Pin": "I3",
  "pulseWidth": 40,
  "pulseInterval": 2000,
  "frameInterval": 25000,
  "LEDColorDefault": "off",
  "LEDColor0": "red",
  "LEDColor1": "green",
  "LEDColor00": "off",
  "LEDColor01": "red",
  "LEDColor10": "green",
  "LEDColor11": "amber",
  "keypressFormat": "FourBit",
  "keypressFacilityCode": 0
}

Field	Type	Description
`nbrOfLEDPins`	Integer	The number of LED control pins that is connected to the access control system. 0, 1 or 2 are supported.
`beeper`	Boolean	True if a beeper control line is connected to the device.
`beeperPin`	Id	The I/O input pin that the beeper is connected to. See IOPinName for additional information.
`LED1Pin`	Id	The I/O input pin that the LED1 is connected to (normally green or red/green). See IOPinName for additional information.
`LED2Pin`	Id	The I/O input pin that the LED2 is connected to (normally red). See IOPinName for additional information.
`pulseWidth`	Integer	The time of the data pulse, measured in μs. `Min 20, Max: 100, Default: 40`.
`pulseInterval`	Integer	The time between data pulses, measured in μs. `Min: 200, Max: 20000, Default: 2000`.
`frameInterval`	Integer	The minimum time between data transfers, measured in μs. `Min: 20000, Max: 1000000, Default: 25000`.
`LEDColorDefault`	Id	The color that is shown if no wires are connected (i.e. `nbrOfLEDPins`. See ColorName for accepted colors.
`LEDColor0`	Id	The color when 1 LED control wire is connected and the state is 0. See ColorName for accepted colors.
`LEDColor1`	Id	The color when 1 LED control wire is connected and the state is 1. See ColorName for accepted colors.
`LEDColor00`	Id	The color when 2 LED control wires are connected and the state is 00. See ColorName for accepted colors.
`LEDColor01`	Id	The color when 2 LED control wires are connected and the state is 01, (LED 1 is 1 and LED2 is 0). See ColorName for accepted colors.
`LEDColor10`	Id	The color when 2 LED control wires are connected and the state is 10, (LED 1 is 0 and LED2 is 1). See ColorName for accepted colors.
`LEDColor11`	Id	The color when 2 LED control wires are connected and the state is 11 (LED 1 is 1 and LED2 is 1). See ColorName for accepted colors.
`keypressFormat`	Id	The PIN code format. See KeypressOutputFormat and ServiceCapabilities for additional information and supported values. Default value is FourBit.
`keypressFacilityCode`	Integer	The facility code to override the PIN code (default is 0). Maximum value depends on the keypress format: 255 for Wiegand26 (8 bits), 65535 for Wiegand34 and Wiegand37FacilityCode (16 bits).

OSDPConfiguration

This chapter shows the configuration options for the OSDP.

{
  "OSDPAddress": 0
}

Field	Type	Description
`OSDPAddress`	Integer	The OSDP PD address (i.e. client). Min=0, Max=126, Default=0.

PinConfiguration

This chapter goes through the configuration options for PIN length and timeout. The PIN should match the one set in the Access Control Unit.

{
  "pinLength": 4,
  "pinTimeout": 10
}

Field	Type	Description
`pinLength`	Integer	The number of digits in the PIN code. Min=0 (PIN is disabled), Max=32, Default=4. This parameter should match the Access control unit configuration.
`pinTimeout`	Integer	The number of seconds that should pass before the device goes back to idle mode when no PIN is received. Min =1, Max=60, Default=10. This parameter should match the Access control unit configuration.

RequestAccessConfiguration

Configuration options for the Axis Request Access protocol. The name is derived from Target and Source unless present in the AccessPoint. See IPAccessConfiguration for additional information.

{
  "Name": "Door - Reader Entrance A8207",
  "Id": "e6608ad31a480904f9646e936cc8e86a",
  "Address": "a1601.example.com",
  "AccessControllerToken": "Axis-00408c184be0+AccessController",
  "SourceToken": "Axis-00408c184be0:1581679815.571711000",
  "TargetToken": "Axis-00408c184be0:1581679815.080670000",
  "AccessPointToken": "Axis-00408c184be0:1581679823.844035000"
}

Field	Type	Description
`Name`	String	The Nicename of the Access point.
`Id`	String	The internal id of the `RequestAccess` (Access point) configuration.
`Address`	String	The address used to access the correct controller.
`AccessControlToken`	String	The access controller token that should be accessed.
`SourceToken`	String	The source token that should be used (Reader / IdPoint.
`TargetToken`	String	The target token that should be used (Door)
`AccessPointToken`	String	The AccessPoint token that should be used.

IPIntegrationProtocol

The supported IP integration protocols. See IPAccessConfiguration for additional information.

Value	Description
`None`	No protocol is selected.
`RequestAccess`	Axis RequestAccess.
`RemoteActivity`	Axis Indicated RemoteActivity.

ProbelIPAccessStatus

The status of a ProbelAccessConfiguration request.

Value	Description
`OK`	Everything is ok.
`NoAccessPoints`	Connection is ok, but could not find any access points.
`UnknownError`	Unknown error.
`ConnectionError`	Failed to connect to the specified address or scheme.
`AuthenticationError`	Failed to authenticate.
`CertificateError`	Failed to validate the certificate.

IPAccessScheme

The supported IP integration transport protocols.

Value	Description
`https`	Encrypted HTTP
`http`	Unencrypted HTTP

IPAccessConfiguration

Configuration options for IP based access control integration. See IP Access configuration for additional information.

{
  "Scheme": "https",
  "Address": "a1601.example.com",
  "Username": "a8207userOnA1601",
  "Password": "a8207passwordOnA1601",
  "VerifyCertificate": true,
  "IPProtocol": "RemoteActivity",
  "RequestAccessConfiguration": {
    RequestAccessConfiguration
  }
}

Field	Type	Description
`Scheme`	String	The scheme that should be used (optional). See IPAccessScheme for additional information.
`Address`	String	The address that access the controller. A typical hostname is `[:port]`.
`Username`	String	The username.
`Password`	String	The password.
`VerifyCertificate`	String	An option to disable the certificate verification. Default value is true.
`IPProtocol`	String	The protocol that should be used (optional). See IPIntegrationProtocol for additional information.
`RequestAccessConfiguration`		The protocol specific configuration.

CompatibilityConfiguration

Shows the card reader compatibility, which makes it possible to extend the configuration options without changing the configuration structures.

{
  "CompatibilityConfigs": [
    {
      Attribute
    },
    ...
  ]
}

Field	Type	Description
`CompatibilityConfigs`	Attribute array	A list of compatibility configuration values. See ServiceCapabilities for additional information.

CardReaderConfiguration

Configurations for the card reader functionality, such as the integration protocol, what card types to enable, etc. All fields are optional, meaning that their current value will be kept unless specified in a Set or Update request.

{
  "Protocol": "Wiegand",
  "CardTypes": [ "EM4X02",..],
  "WiegandConfiguration": {
    WiegandConfiguration
  },
  "OSDPConfiguration": {
    OSDPConfiguration
  },
  "PinConfiguration": {
    PinConfiguration
  },
  "IPAccessConfiguration": {
    IPAccessConfiguration
  },
  "CompatibilityConfiguration": {
    CompatibilityConfiguration
  },
  "RegisteredReaderConfiguration": {
    RegisteredReaderConfiguration
  },
  "OutputFormat": {
    OutputFormatConfiguration
  }
  "SensitiveRFIDEventEnabled": false,
  "SensitivePINEventEnabled": false
}

Field	Type	Description
`Protocol`	Id	The protocol that should be used. See AccesscontrolIntegrationProtocol for additional information.
`CardTypes`	Id array	A list of card types that should be accepted. See CardTypeNames for capabilities and possible values.
`WiegandConfiguration`	WiegandConfiguration	The Wiegand configuration.
`OSDPConfiguration`	OSDPConfiguration	The OSDP configuration.
`PinConfiguration`	PinConfiguration	The PIN configuration.
`IPAccessConfiguration`	IPAccessConfiguration	The `IPAccessConfiguration`.
`CompatibilityConfiguration`	CompatibilityConfiguration	Compatibility flags.
`RegisteredReaderConfiguration`	RegisteredReaderConfiguration	Specifies how the clients (typically an application) are allowed to use `InjectTag`.
`OutputFormat`	OutputFormatConfiguration	Specifies how the card data should be formatted.
`SensitiveRFIDEventEnabled`	Boolean	True if the actual UID and card number is present in events.
`SensitivePINEventEnabled`	Boolean	True if the actual PIN is present in events.

TagUidType

The type used for the UID of a tag. Base type is string, maxLength = 64 and minLength = 0.

TagPresentedInfo

Describes the tag together with the metadata.

{
  "TagUid": "CA4DDA7A",
  "BitCount": 32,
  "TagType": "MIFARE_Classic",
  "ReaderId": "Internal",
  "Age": 1,
  "FacilityCode": "",
  "CardNumber": "",
  "Format": "Raw",
  "Masked": true
}

Field	Type	Description
`TagUid`	TagUidType	The UID of the tag.
`BitCount`	Integer	The number of bits in TagUid.
`TagType`	Id	Identifies the tag type, e.g. `MIFARE_CLASSIC`. See CardTypeNames for additional information.
`ReaderId`	Id	The ID of the reader. “Internal” is the default name for the built-in reader, but this can be set with an `InjectTag` call.
`Age`	Integer	How much time has passed since the tag was presented, measured in seconds.
`FacilityCode`	Id	The facility code in decimals. Please note that a number can be to big for the integer. Null or ”“ means that the facility code is not present on the detected or selected format.
`CardNumber`	Id	The card number in decimals. Please note that a number can be to big for the integer. Null or ”“ means that the card number is not present on the detected or selected format.
`Format`	Id	The detected card data format. Default value is Raw. See ServiceCapabilities for supported values.
`Masked`	Boolean	True if the reader is masked. Default value is false.

CardDataSources

Defines the possible data sources. All card types supports CSN (Card serial number), but other sources may be possible depending on the card type.

Value	Description
`CSN`	Uses Card serial number (CSN) as the input.
`SecureId`	Uses the secure id as the input, e.g. iClass PAC bits or MIFARE DesFire SecureId configured for Random Id.
`Data`	Uses data retrieved as the input.

RegisteredReaderPolicy

Lets you mask the newly registered readers.

Value	Description
`Fixed`	Ignores masking so that only defined ReaderIds in the RegisteredReaderConfiguration are allowed to send an InjectTag to the Access control.
`Auto`	The default value that accepts the masking request provided by the application readers. Masking is provided in the RegisterReader call.

RegisteredReaderConfiguration

Specifies how the clients (usually an application) are allowed to use the InjectTag.

{
  "ReaderIds": [ "Internal",.. ],
  "Policy": "Auto"
}

Field	Type	Description
`ReaderIds`	Id array	Lists the readers that are allowed to send an `InjectTag` to access the control integration using Protocol. The default value is `Internal`. This can only be done when Policy is Fixed. See RegisteredReaderPolicy for additional information.
`Policy`	Id	The policy that should be used. See RegisteredReaderPolicy for additional information.

IntercomReaderIds

Defines the readers provided by the reader that can be masked.

Value	Description
`Internal`	The built-in reader.

ReaderIdWithMask

Shows if the reader is masked or not.

{
  "readerId": "Internal",
  "isMasked": true
}

Field	Type
`readerId`	Id
`isMasked`	Boolean

Service capabilities

The GetServiceCapabilities call can be used to retrieve the capabilities of a service, such as extensions and product specific capabilities and implementation methods.

IntegerValidator

Assigns min/max values to an integer and performs the client side validation of the user input.

{
  "Name": "pinLength",
  "Min": 0,
  "Max": 32
}

Field	Type	Description
`Name`	Id	Identifies the integer in the configuration.
`Min`	Integer	Minimum value of the integer.
`Max`	Integer	Maximum value of the integer.

CompatibilityFlag

The available CompatibilityConfig names used in Attribute and AttributeInfo.

Value	Description
`ByteReversal`	Reverses the byte order for UUID (all card types and bit lengths).
`Max32bit`	Uses maximum 32 bits of the UUID (all card types and bit lengths).

ServiceCapabilities

Reflects the optional, static functionality of a service that won’t change when a device is active.

{
  "Version": "string",
  "Call": true,
  "DTMFEvent": true,
  "CallButton": true,
  "CallKeypad": true,
  "PinKeypad": true,
  "Reader": true,
  "uiLeds": [{UiLed},..],
  "AccesscontrolIntegrationProtocols": ["None",..],
  "SupportedCards": [{CardType},..],
  "SupportedIOPins": ["I1",..],
  "SupportedColorNames": ["off",..],
  "IntegerValidators": [{IntegerValidator},..],
  "CompatibilityConfigs": [{AttributeInfo},..],
  "SupportedKeypressOutputFormatWiegand": ["FourBit",..],
  "SupportedCardOutputFormat": ["Raw",..],
  "SupportedFacilityCodeOverrideMode": ["Auto",..],
  "SupportedParityType": ["None",..],
  "SupportedCallButtonIdleBehavior": ["Automatic",..],
  "SupportedDefaultContactSorting": ["SortByFirstName",..],
  "SupportedDefaultNameFormat": ["FirstNameFirst",..],
}

Field	Type	Description
`Version`	String	The service version.
`Call`	Boolean	True if Call is supported.
`DTMFEvent`	Boolean	True if DTMFEvent operations are supported.
`CallButton`	Boolean	True if Callbutton is available.
`CallKeypad`	Boolean	True if Keypad is available.
`PinKeypad`	Boolean	True if a Pinpad is available.
`Reader`	Boolean	True if your device has a reader.
`uiLeds`	UiLed array	Lists all LED-lights available on your system.
`AccesscontrolIntegrationProtocols`	ID array	Lists the communication protocols with supported access controller. See AccesscontrolIntegrationProtocol for possible values.
`SupportedCards`	CardType array	Lists supported card types.
`SupportedIOPins`	ID array	Lists supported I/O pins. See IOPinName for possible values.
`SupportedColorNames`	ID array	Lists supported color names. See ColorName for possible values.
`IntegerValidators`	IntegerValidator array	Lists limits for integer configuration fields.
`CompatibilityConfigs`	AttributeInfo array	Lists supported compatibility configuration values. See CompatibilityFlag for possible values.
`SupportedKeyPressOutputFormatWiegand`	ID array	Lists the supported keypress formats for wiegand. See KeypressOutputFormat for possible values.
`SupportedCardOutputFormat`	ID array	Lists the supported card formats. See CardOutputFormat for possible values.
`SupportedFacilityCodeOverrideMode`	ID array	Lists the supported facility code override modes. See FacilityCodeOverrideMode for possible values.
`SupportedParityType`	ID array	Lists the supported parity types. See ParityType for possible values.
`SupportedCallButtonIdleBehavior`	ID array	Lists the supported call button idle behavior. See CallButtonIdleBehavior for possible values.
`SupportedDefaultContactSorting`	ID array	Lists the possible values for default contact sorting. See DefaultContactSorting for possible values.
`SupportedDefaultNameFormat`	ID array	Lists the supported default name format values. See DefaultNameFormat for possible values.

GetServiceCapabilities commands

Returns the capabilities of the service.

Request

{}

Empty.

Response

{
  "Capabilities": {ServiceCapabilities}
}

The capability response message. Contains the requested Call service capabilities.

Configuration

The configuration options for the overall functionality are managed through the data structure and retrieved by using a GetConfiguration command or a REST:ful GET resource along with a GET command to /vapix/intercom/Configuration, while using either UpdateConfiguration or REST:ful with a POST to /vapix/intercom/Configurationcan be employed when you want to modify a configuration. It is possible to update selected parts of the configuration with the latter command by selecting the fields that should be changed.

Configuration types

Configuration

This command is used to configure an entity for the intercom functionality. An optional field not set by SetConfiguration will keep its current value.

{
  "Version": "string",
  "CallTriggersEnabled": true,
  "CallByNumbersEnabled": true,
  "DefaultContractSorting": "SortByFirstName",
  "DefaultNameFormat": "FirstNameFirst",
  "DefaultCallByNumberSIPAccountId": "Id",
  "AudioclipVolume": 100,
  "BeeperVolume": 80,
  "PresenceTimeout": 12,
  "CardReaderConfiguration": {CardReaderConfiguration},
  "CallButtonIdleBehavior": "Automatic"
}

Field	Type	Description
`Version`	String	The configuration version.
`CallTriggersEnabled`	Boolean	True if the processing triggers in the `PhonebookEntries` are enabled.
`CallByNumbersEnabled`	Boolean	True if calls to dialed numbers that does not match any `CallRule` is enabled.
`DefaultContactSorting`	DefaultContactSorting	The default method when sorting contacts.
`DefaultNameFormat`	DefaultNameFormat	The default format for the contact names.
`DefaultCallByNumberSIPAccountId`	Id	The default SIPAccount used by `CallByNumber` (optional).
`AudioclipVolume`	Integer	The volume for the built-in audio files (button presses, calling, ringing, etc.) `Min: 0, Max: 1000, Default: 100`.
`BeeperVolume`	Integer	The volume for the beeper (Wiegand and OSDP) feedback. `Min: 0, Max: 100, Default: 80`.
`PresenceTimeout`	Integer	The time (in seconds) before user presence is timed out. `Min: 2, Max: 86400, Default: 12`.
`CardReaderConfiguration`	CardReaderConfiguration	The card reader related configurations.
`CallButtonIdleBehavior`	CallButtonIdleBehavior	The idle behavior for the call button.

DefaultContactSorting

The default method for sorting contacts.

Value	Description
`SortByFirstName`	Sorts the contacts alphabetically according to their first names.
`SortByLastName`	Sorts the contacts alphabetically according to their last names.

DefaultNameFormat

The default format for the contact names.

Value	Description
`FirstNameFirst`	Name entries will be formatted according to `FirstName` + " “ + `LastName`.
`LastNameFirst`	Name entries will be formatted according to `LastName` + " “ + `FirstName`.

SetConfiguration

This method is used to set the general configuration for the intercom.

Request

{
  "Configuration": { 
    Configuration
  }
}

Parameter	Description
`Configuration`	The configuration that should be set.

Response

{}

Parameter	Description
`{}`	Empty.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of input.

UpdateConfiguration

This method is used to update the general configuration. Optional fields not present in the request will keep their current values.

Request

{
  "Configuration": { Configuration }
}

Parameter	Description
`Configuration`	The configuration that should be set.

Response

{}

Parameter	Description
`{}`	Empty.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of inputs.

GetConfiguration

This method is used to request the full configuration for the intercom.

Request

{
  "includeImageFile": <boolean>
}

Parameter	Description
`includeImageFile`	If set to true, all `imageFile` fields will be included in the response (optional).

Response

{
"Configuration": { Configuration }
}

Parameter	Description
`Configuration`	The configuration structure.

Configuration

This method implements the REST API for the device configuration and handles both GET, SET and REMOVE.

Use GET /vapix/intercom/Configuration to fetch the configuration.
Use POST /vapix/intercom/Configuration to initiate the UpdateConfiguration .
Use PUT /vapix/intercom/Configuration to initiate the SetConfiguration.

Request

{
  "includeImageFile": <boolean>,
  "Configuration": {
    Configuration
  },
  "imageFile": {
    ImageFile
  }
}

Parameter	Description
`includeImageFile`	If set to true, all `imageFile` fields will be included in the response (optional).
`Configuration`	The configuration that should be set.
`imageFile`	The image file that should be used to update an image.

Response

{
  "Configuration": {
    Configuration
  }
}

Parameter	Description
`Configuration`	The configuration structure.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of inputs.

Server report

CallButtonInformation

This method summaries the call button configuration.

{
  "VMSCallEnabled": true,
  "NumberOfRecipients": 0
}

Parameter	Type	Description
`VMSCallEnabled`	Boolean	The current status of the `CallButtonVMS`.
`NumberOfRecipients`	Integer	The number of contacts for the call button.

ContactsInformation

This method summarizes the contact configurations.

{
  "NumberOfContacts": 0,
  "NumberOfOrganizations": 0
}

Parameter	Type	Description
`NumberOfContacts`	Integer	The total number of contacts.
`NumberOfOrganizations`	Integer	The total number of organizations.

GetServerReport

This method is used when you want to return the safe and desired parts of the server report.

Request

{}

Response

{
  "Configuration": {Configuration},
  "DiscardedFields": ["string", ...],
  "CallButtonInformation": {CallButtonInformation},
  "ContactsInformation": {ContactsInformation}
}

Parameter	Description
`Configuration`	A structure containing the configuration fields.
`DiscardedFields`	The configuration fields discarded due to containing sensitive data.
`CallButtonInformation`	The call button information.
`ContactsInformation`	The contact information.

Card reader configuration and operation

Supported card reader operations:

Parameter	Description
`GetCardReaderConfiguration`	Alternative operation to `GetConfiguration` when only the `CardReaderConfiguration` part is needed.
`GetSupportedTagTypes`	Retrieve a list of tag types supported by the reader. This operation is also available with `GetServiceCapabilities`.
`GetDefaultTagTypes`	Retrieve a list with the default enabled card types.
`GetLastTag`	Retrieve the UID of the last presented tag.
`InjectTag`	Simulates presenting an RFID tag, which is useful when you are integrating with a third party application and acts as a filter and/or transforms the tag information.
`RegisterReader`	Registers either an external or application reader to be used when processing tags.
`UnregisterReader`	Unregisters either an external or application reader to be used when processing tags.
`KeepAliveReader`	Extends a registration.
`GetCurrentReaders`	Exposes the currently available readers.

GetCardReaderConfiguration

This method is used when you want to send out a request for the full configuration.

Request

{}

Parameter	Description
`{}`	Empty.

Response

{
  "CardReaderConfiguration": {
    CardReaderConfiguration
  }
}

Parameter	Description
`CardReaderConfiguration`	The configuration structure.

GetSupportedTagTypes

This method is used when you want to retrieve a list of tag types supported by the reader.

Request

{}

Parameter	Description
`{}`	Empty.

Response

{
  "CardTypes": [
    {
      CardType
    },
    ...
  ]
}

Parameter	Description
`CardTypes`	The supported tag types.

GetDefaultTagTypes

This method is used when you want to retrieve a list of tag types enabled by default.

Request

{}

Parameter	Description
`{}`	Empty.

Response

{
  "CardTypes": [
    "<Id>",
    ...
  ]
}

Parameter	Description
`CardTypes`	The default card types.

GetLastTag

This method is used when you want to retrieve the UID of the last tag that was presented.

Request

{
  "ReaderId": "<Id>"
}

Parameter	Description
`ReaderId`	Optional reader ID that the last tag should be retrieved from. The last tag will be retrieved If this parameter is not specified.

Response

{
  "Tag": {
    TagPresentedInfo
  }
}

Parameter	Description
`Tag`	The UID of the tag last seen.

Error codes

Code	Description
`ter:NotFound`	No tag with the specified reader id was found.
`env:Receiver` `ter:ActionNotSupported` `ter:NotSupported`	The method is not supported.

GetTag

This method is used when you want to retrieve the UID of either the last presented tag or one recently presented that optionally matches the specified timestamp taken from the Device/Intercom/RFID event notification. If neither ReaderId nor timestamp is specified, the last tag will be returned

Request

{
  "ReaderId": "<Id>",
  "timestamp": "<string>"
}

Parameter	Description
`ReaderId`	Optional reader ID that the last tag should be retrieved from. The last tag will be retrieved If this parameter is not specified.
`timestamp`	A timestamp of the tag taken from the Device/Intercom/RFID event notification. Providing the timestamp assures that the data corresponds to the event received.

Response

{
  "Tag": {
    "TagPresentedInfo"
  }
}

Parameter	Description
`Tag`	The UID of the matching the input parameters.

Error codes

Code	Description
`ter:NotFound`	No tag with the specified reader ID and timestamp was found.
`ter:NotSupported`	The method is not supported.

InjectTag

This method is used when you want to simulate presenting an RFID tag to the intercom reader. If the internal reader has been masked, it is recommended to make sure that the ReaderId is no longer Internal in the supplied tag.

Request

{
  "Tag": {
    TagPresentedInfo
  },
  "CardData": [
    {
      CardData
    },
    ...
  ]
}

Parameter	Description
`Tag`	The tag that should be set up.
`CardData`	The card data that is returned.

Response

{}

Parameter	Description
`{}`	Empty.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of input.
`env:Receiver` `ter:ActionNotSupported` `ter:NotSupported`	The method is not supported.

RegisterReader

This method is used when you want to register an external application reader that can be used to process tags. This makes it possible to mask the internal reader so a tag from a normal card swipe don’t use a configured integration protocol.

Request

{
  "ReaderId": "<Id>",
  "DisableInternalReader": <boolean>
  "MaskedReaderIds": [
    "<Id>",
    ...
  ],
  "UnmaskIfLost": <boolean>
}

Parameter	Description
`ReaderId`	The ID of the external reader.
`DisableInternalReader`	If this parameter exists and is true all internal readers will be added to `MaskedReaderIds` automatically (optional).
`MaskedReaderIds`	The reader ID for internal and external application readers that can be masked. Masked readers are not allowed to send credentials to the Access control, but the data will still be available as an RFID event. Default value doesn’t mask anything and the values for the internal reader Ids can be found in `IntercomReaderIds` enum.
`UnmaskIfLost`	If true the masked readers will be released when the timeout expires (optional). The default value is false.

Response

{
  "Timeout": <int>
}

Parameter	Description
`Timeout`	The timeout, measured in seconds, until the registration expires.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of input.
`env:Receiver` `ter:Action` `ter:Failure`	The operation failed.

UnregisterReader

This method is used when you want to un-register either an external reader or an application reader from being used to process tags.

Request

{
  "ReaderId": "<Id>",
}

Parameter	Description
`ReaderId`	The Id of the external reader.

Response

{}

Parameter	Description
`{}`	Empty.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of input.

KeepAliveReader

This method is used when you want to extend the timeout given in the RegisterReader call. An error will be returned if no call was made for the ReaderId or if it had already timed out.

Request

{
  "ReaderId": "<Id>",
}

Parameter	Description
`ReaderId`	The Id of the external reader.

Response

{
  "Timeout": <int>
}

Parameter	Description
`Timeout`	Timeout in seconds until the registration expires.

Error codes

Code	Description
`env:Sender` `ter:InvalidArgVal`	The request contains an invalid argument.
`env:Sender` `ter:InvalidArgs`	The request is missing something or has an invalid combination of input.

GetCurrentReaders

This method is used when you want to expose currently available readers.

Request

{}

Parameter	Description
`{}`	Empty.

Response

{
  "Readers": [
    {
      ReaderIdWithMask
    },
    ...
  ]
}

Parameter	Description
`Readers`	The array of strings with the available `ReaderIds` together with a masked flag.

IP Access configuration

The IPAccessConfiguration and RequestAccessConfiguration structures in the CardReaderConfiguration are used when IPAccess is selected as the AccesscontrolIntegrationProtocol.

Using IPIntegrationProtocol (IPProtocol) in the IPAccessConfiguration defines the protocol, while RequestAccess and RemoteActivity creates outbound connections to the access controller by using the configuration found in RequestAccessConfiguration. The RequestAccess uses a HTTP request with a command to the Access control service to send card and PIN information as well as the returned AccessGranted value and Reason to provide feedback to the user.

RemoteActivity creates and keeps a websocket connection to the IdPoint service of the controller by receiving notifications in order to maintain the proper feedback state. It also have the benefit of keeping track of the full access controller feedback whereas RequestAccess only provides feedback for operations initiated by your Intercom device.

The ProbeIPAccessConfiguration and UpdateIPAccessConfiguration functions can be used to set up integrations with door controllers, where IPIntegrationProtocol (IPProtocol) in IPAccessConfiguration will be determined based on the capabilities detected in the controller when these functions are used.

Enumeration: ProbeIPAccessStatus

The status of a ProbeIPAccessConfiguration request.

Value	Description
`OK`	Everything is OK.
`NoAccessPoints`	Connection is OK, but could not find any access points.
`UnknownError`	Unknown error.
`ConnectionError`	Failed to connect to the specified address and scheme.
`AuthenticationError`	Failed to authenticate.
`CertificateError`	Failed to validate the certificate.

IPAccessOption

This structure is returned as a response to IP Access configuration.

{
  "Name": "Door - Reader Entrance A8207",
  "Id": "e6608ad31a480904f9646e936cc8e86a",
  "IPProtocol": "RemoteActivity"
}

Field	Type	Description
`Name`	String	The door name visible to the user.
`Id`	String	The internal ID of the `RequestAccess` configuration.
`IPProtocol`	String	The detected protocol. See IPIntegrationProtocol for additional information.

ProbeIPAccessConfiguration

Probe an IP based access controller and return a list of selectable configurations. Please note that any current configuration will be overridden by the specified input parameters. Also, the ID of the desired IPAccessOption should be supplied to UpdateIPAccessConfiguration.

Request

{
  "IPAccessConfiguration": {
    IPAccessConfiguration
  }
}

Parameter	Description
`IPAccessConfiguration`	The `IPAccessConfiguration`

Response

{
  "Status": "<string>",
  "StatusText": "<string>"
  "IPAccessOptions": [
    {
      IPAccessOption
    },
  ],
  "SuggestedId": "<string>",
  "CurrentName": "<string>"
}

Parameter	Description
`Status`	The status of the probe request. See IP Access configuration for additional information.
`StatusText`	Textual status related to `Status`.
`IPAccessOptions`	A list of options.
`SuggestedId`	A configuration ID that matches the current configuration. No match will be found if it gets omitted.
`CurrentName`	The name of the current configuration that can be used as a hint if `SuggestedId` is not present.

UpdateIPAccessConfiguration

Update the IPAccessConfiguration based on the selected IPAccessOption in the response from a previous ProbeIPAccessConfiguration.

Request

{
  "Id": "<string>",
}

Parameter	Description
`Id`	The ID from an IPAccessOption previously returned from ProbeIPAccessConfiguration

Response

{
  "IPAccessConfiguration": {
    IPAccessConfiguration
  }
}

Parameter	Description
`IPAccessConfiguration`	The resulting configuration.

Keypress functions

Key presses can be monitored by using the Device/Intercom/KeyPin event in Third party integration, or pulled with GetLastKeySequence.

A KeySequence can be simulated by using InjectKeySequence. This can also be used with third-party integrations to provide a PIN number, such as validating a face instead of forcing the user to enter a PIN code.

The keypad on an intercom can be used both to place calls and to enter a PIN by operating in different modes. For example, if the intercom is not in PIN mode, the # key must be pressed to end the PIN entry.

Keypress types

The following identifiers should be used in the source field of a InjectKeySequence call and for the KeyPin event.

Enumeration: PinSourceType
Value	Description
`Internal`	Used by internal intercom components.
`Unknown`	Used when no other source is provided.

GetLastKeySequence

This method is used when you want to retrieve a string containing the latest key sequence. The sequence is automatically reset when new keys are entered after a complete sequence. A sequence is completed by # or the call button ('C') or when the number of digits match the configured pin length when in PIN mode. The optional timestamp should be taken from the Device/Intercom/KeyPin event notification. In cases where no timestamp is specified the last key sequence from a specified source will be returned, while the last used key sequence will be returned if neither source nor reader is specified.

Request

{
  "Source": <string>,
  "timestamp": <string>
}

Parameter	Description
`Source`	An optional source identifier to retrieve the key sequence from. If not specified, the last source of key sequence will be used. See Keypress functions for reserved identifiers.
`timestamp`	A timestamp of the key sequence taken from the Device/Intercom/KeyPin event notification. Providing the timestamp assures that the data corresponds to the event received, but is not mandatory.

Response

{
  "KeySequence": <string>,
  "Source": <string>,
  "timestamp": <string>
}

Parameter	Description
`KeySequence`	The the key sequence.
`Source`	The source of this key sequence.
`timestamp`	The timestamp of this key sequence.

InjectKeySequence

This method is used when you want to simulate key presses.

Depending on the KeyPadState (see tns1:Device/tnsaxis:Intercom/KeypadState), the sequence must be ended with a C to make a call or # to process the key sequence as a PIN.

No ending # is required when the state is KSM_PIN_MODE. The same state is automatically entered after a card swipe if Wiegand or OSDP has been configured, or if the SetUiFeedback call is used together with RequirePIN or PINPadRequest as highlevelFeedbacks.

Request

{
  "KeySequence": <string>,
  "Source": <string>
}

Parameter	Description
`KeySequence`	The key sequence.
`Source`	Identifies the component that posted the `InjectKeySequence` call. See Keypress functions for potential identifiers.

Response

{}

Parameter	Description
`{}`	Empty.

Feedback functions

Contains the different kinds of feedback commands that the UI components can present.

Feedback types

UIHighLevelFeedback

This table describes the feedback that can be received.

Value	Description
`LowlevelControl`	LED and/or audio feedback, typically over Wiegand or OSDP.
`AccessGranted`	The access controller signals that access is granted.
`AccessDenied`	The access controller signals that access is denied.
`EarlyRFID`	Indicates the act of a presenting a tag.
`PINPadRequest`	Indicates that the user is requested to enter a PIN.
`PINPadCancel`	Indicates that the user canceled entering a PIN.
`Other`	The feedback mode is specified in some other defined way.
`Idle`	The normal state, typically `DoorLocked` or `DoorUnlocked` is used when the device controls a door.
`DoorLocked`	Indicates that the door is locked.
`DoorUnlocked`	Indicates that the door is unlocked.
`DoorOpenTooLong`	Indicated that the door has been open for too long.
`DoorPreAlarmWarning`	Indicates that the door is about to have been open too long.
`RequirePIN`	PIN (Personal Identification Number) code required.
`RequireCard`	A card is required.
`Processing`	Processing in progress.
`InvalidCredential`	Credential is not valid.
`AccessGrantedAndRequired`	Access granted with further identification possible.
`Ok`	Generic Ok indication.
`Fault`	Generic Fault indication.
`Warning`	Generic Warning indication.
`Alarm`	Generic Alarm indication.
`Custom`	The custom mode.
`Progress`	Indicates whether progress has been made.
`AuthenticationFailed`	The authentication process failed.
`RequireInteraction`	Additional interaction required.

RunStyleType

Defines the supported types of run style.

Value	Description
`oneshot`	The feedback is processed once and then removed.
`permanent`	The feedback is processed over and over again.

TargetLedType

The name of the LED types that the UiLedFeedback should be applied to.

Value	Description
`backlight`	The backlight for the keypad.
`callButton`	The call button.
`stripe`	Mainly used for access control feedback.
`statusDoor`	The door status indicator.
`statusCall`	The calling status indicator.
`statusSpeak`	The speak/active call status indicator.

LedControlType

The control type for the different LEDs.

Value	Description
`none`	None.
`onoff`	Simple on/off switch.
`pwm`	PWM (Pulse Width Modulation) LED.
`rgb`	RGB LED.
`rgbpwm`	PWM RGB LED.

CallButtonIdleBehavior

Describes the possible idle behavior value for the call button.

Value	Description
`Automatic`	The visualization specified in the configuration file `etc/sysconfig/dsui.conf`.
`Off`	Visualization switched off.
`On`	Visualization at full power.

UiLed

Lists information about the LEDs available on the device.

{
  "ledId": "stripe",
  "ledType": "rgbpwm"
}

Field	Type	Description
`ledId`	TargetLedType	The name of the LED.
`ledType`	LedControlType	How the LED is controlled.

FeedbackSourceType

The identifiers used in the source field of the SetUIFeedback call.

Value	Description
`Internal`	Used by the internal components of the intercom.

UILedFeedback

Blinks a LED for a duration of time or during a loop.

See ColorName if the returning value is textual.

If the value is in hexadecimal (#RRGGBB) it will be interpreted as Monochrome vs RGB:

If monochrome, only the LSB is effective.
If RGB, 1st LSB corresponds to blue, 2nd LSB corresponds to green and 3rd LSB corresponds to red.
MSB is not used.

Another possible value can be retrieved from PWM vs regular:

If PWM, all values between 0–255 are valid.
For non-PWM, 0 = off, 1–255 = on.

{
  "led": "backlight",
  "runStyle": "oneshot",
  "durationOnMillisec": 0,
  "durationOffMillisec": 0,
  "valueOn": "off",
  "valueOff": "off",
  "loops": 0,
  "handled": true
}

Field	Type	Description
`led`	String	The LED name. See TargetLedType.
`runStyle`	String	The running style. See RunStyleType.
`durationOnMillisec`	Integer	Duration for the ON state.
`durationOffMillisec`	Integer	Duration for the OFF state.
`valueOn`	String	Value for the ON state.
`valueOff`	String	Value for the OFF state.
`loops`	Integer	The number of loops that should be run.
`handled`	Boolean	Initially `FALSE`. Used to mark that his particular feedback has already been displayed.

UiAudioFeedback

Signals either a beeper sound or an audio file to play.

{
  "durationOnMillisec": 0,
  "durationOffMillisec": 0,
  "loops": 0,
  "handled": true,
  "file": "string"
}

Field	Type	Description
`durationOnMillisec`	Integer	The duration for the ON state.
`durationOffMillisec`	Integer	The duration for the OFF state.
`loops`	Integer	The number of loops that should be run.
`handled`	Boolean	Initially `FALSE`. Used to mark that his particular feedback has already been displayed.
`file`	String	The audio file that should be played.

UiGraphicFeedback

Describes the graphic that can be retrieved.

{
  "image": "string",
  "durationMillisec": 0
}

Field	Type	Description
`image`	String	The path to image or base64 encoded data url format.
`durationMillisec`	Integer	The duration for the image.

SetUiFeedback

Sets the behavior for the user interface feedback.

Request

{
  "highlevelFeedbacks": [
    <string>,
    ...
  ],
  "ledFeedbacks": [
    {
      UiLedFeedback
    },
    ...
  ],
  "audioFeedback": {
    UiAudioFeedback
  },
  "source": <string>,
  "text": <string>,
  "attributes": [
    {
      Attribute
    },
    ...
  ],
  "graphicFeedback": {
    UiGraphicFeedback
  }
}

Parameter	Description
`highlevelFeedbacks`	List the set high level feedbacks. See UIHighLevelFeedback for defined values.
`ledFeedbacks`	Lists of LED feedbacks to set.
`audioFeedback`	The audio feedback.
`source`	An arbitrary identifier on the component that posts the feedback call. See FeedbackSourceType for reserved identifiers.
`text`	Text to display or speak.
`attributes`	List of attributes for additional information and future extensions.
`graphicFeedback`	The graphic feedback that should be set.

Response

{
  "Result": <boolean>
}

Parameter	Description
`Result`	The result of the operation.

Websocket functions

The following types and functions are intended to be used over websockets to subscribe to notifications and do efficient API calls.

The service supports websocket on the /vapix/intercomws endpoint. All RPC functions in this API can be used over a websocket, preferably in the Google JSON or JSONRPC2.0 format.

The methods and types in the Intercom service include the namespace prefix axdsapi, which must be used when subscribing to function notifications. Subscribing to events over the websocket is done with the axev:subscribe call. This will generally supply a list of event topics as well as a list of functions, the latter of which also must include the axev:notify function.

To list all possible events, the function axev:getSupported should be used, while event notifications must be sent as an axev:notify method call.

axev:subscribe example

{
  "apiVersion": "1.0",
  "method": "axev:subscribe",
  "params": {
    "style": "ttMessage",
    "functions": [
      "axev:notify",
      "axdsapi:UpdateConfiguration",
      "axdsapi:SetUiFeedback"
    ],
    "topics": ["Device\/Intercom\/RFID", "Device\/Intercom\/KeyPin"]
  },
  "id": "firstsubscribe"
}

RFID event notification over websocket

{
  "apiVersion": "1.0",
  "method": "axev:notify",
  "params": {
    "notifications": [
      {
        "topic": "tns1:Device\/tnsaxis1:Intercom\/RFID",
        "timestamp": "2020-10-04T11:30:08.885643Z",
        "data": {
          "Source": {
            "SimpleItem": [
              {
                "Name": "Source",
                "Value": "Internal"
              }
            ]
          },
          "Data": {
            "SimpleItem": [
              {
                "Name": "UIDFormat",
                "Value": "Raw"
              },
              {
                "Name": "TagType",
                "Value": "MIFARE_Classic"
              },
              {
                "Name": "BitCount",
                "Value": "32"
              },
              {
                "Name": "UID",
                "Value": "CODE1234"
              }
            ]
          }
        }
      }
    ]
  }
}

Limitations

All types have an upper limit of 100 entities/type and while the Intercom service itself cannot enforce this limitation, exceeding it may cause unexpected behavior.

Notification topics

Reader notification topics

tns1:Device/tnsaxis:Intercom/RFID event

This event is used to provide information about a detected RFID card.

The UID and card numbers are sent in plaintext if CardReaderConfiguration.SensitiveRFIDEventEnabled is true, otherwise they are sent as empty strings. If CardReaderConfiguration.SensitiveRFIDEventEnabled is false, you should use the GetLastTag method to retrieve the card information.

The Masked field will be true whenever the event comes from a masked reader, and should therefore not be used for final access decisions by an access control system. The data from a masked reader is not sent over the configured access control integration protocol (VAPIX reader, OSDP or Wiegand) and only available as an event for 3rd party integrations.

Whenever a RFID tag is detected, the device will provide the following events:

Topic: tns1:Device/tnsaxis:Intercom/RFID

<tt:MessageDescription IsProperty="false">
  <tt:Source>
    <tt:SimpleItemDescription Name="Source" Type="xs:string"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="UIDFormat" Type="xs:string"/>
    <tt:SimpleItemDescription Name="TagType" Type="xs:string"/>
    <tt:SimpleItemDescription Name="TagSubType" Type="xs:string"/>
    <tt:SimpleItemDescription Name="UID" Type="xs:string"/>
    <tt:SimpleItemDescription Name="BitCount" Type="xs:int"/>
    <tt:SimpleItemDescription Name="CardNumber" Type="xs:int"/>
    <tt:SimpleItemDescription Name="CardNumberBitCount" Type="xs:int"/>
    <tt:SimpleItemDescription Name="FacilityCode" Type="xs:int"/>
    <tt:SimpleItemDescription Name="FacilityCodeBitCount" Type="xs:int"/>
    <tt:SimpleItemDescription Name="Masked" Type="xs:bool"/>
  </tt:Data>
</tt:MessageDescription>

Field name	Type	Description
`Source/Source`	String	The source of events, such as the Reader Id. Generally Internal, unless `InjectTag` is used.
`Data/UIDFormat`	String	The format of the UID. See CardOutputFormat for additional information.
`Data/TagType`	String	The type of card/tag.
`Data/TagSubType`	String	The card sub type, such as Classic1, Classic4k, DESFire or Ultralight.
`Data/UID`	String	ASCII hex representation of the tag UID if `SensitiveRFIDEventEnabled` is true. The value will be empty otherwise.
`Data/BitCount`	Integer	The number of bits in the UID.
`Data/CardNumber`	Integer	The decimal representation of the card number.
`Data/CardNumberBitCount`	Integer	The number of bits in the `CardNumber`.
`Data/FacilityCode`	Integer	The decimal representation of the facility code.
`Data/FacilityCodeBitCount`	Integer	The number of bits in the `FacilityCode`.
`Data/Masked`	Boolean	True if the reader is masked.

User interface notification topics

tns1:Device/tnsaxis:Intercom/MainState event

The values for the MainState.

Value	Description
`MSM_IDLE`	Idle, waiting for input.
`MSM_KEYING`	Key input in progress.
`MSM_CONVERSATION`	Conversation in progress.

This event provides information about machine transitions.

Whenever there is a transition from one to another main state, the device provides the following events:

Topic: tns1:Device/tnsaxis:Intercom/MainState

<tt:MessageDescription IsProperty="true">
  <tt:Source>
    <tt:SimpleItemDescription Name="Source" Type="xs:string"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="State" Type="xs:string"/>
    <tt:SimpleItemDescription Name="Presence" Type="xs:int"/>
  </tt:Data>
</tt:MessageDescription>

Field name	Type	Description
`Source/Source`	String	The source of events, generally Internal.
`Data/State`	String	The state, as shown in the table above.
`Data/Presence`	Integer	Presence flag. Value=1 when a presence is detected, value=0 otherwise.

tns1:Device/tnsaxis:Intercom/KeyPin event

This event informs the subscribing client about the input key PIN value.

Whenever the key PIN is entered it is published as an event. The key PIN is terminated with # in cases when it is not completed as per the configuration in the reader and will be sent in plaintext if CardReaderConfiguration.SensitiveKeyPinEventEnabled is true or otherwise as the value of an empty string "". If CardReaderConfiguration.SensitiveKeyPinEventEnabled is false you should use the GetLastKeySequence method to fetch the PIN.

Topic: tns1:Device/tnsaxis:Intercom/KeyPin

<tt:MessageDescription IsProperty="false">
  <tt:Source>
    <tt:SimpleItemDescription Name="Source" Type="xs:string"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="KeyPin" Type="xs:string"/>
  </tt:Data>
</tt:MessageDescription>

Field name	Type	Description
`Source/Source`	String	A component identifier for the input that published `KeyPin`(optional). See Keypress functions for potential identifiers.
`Data/KeyPin`	String	The key PIN digits value, either with or without the `#` terminator. If `CardReaderConfiguration.SensitiveKeyPinEventEnabled` is false, value is empty.

tns:Device/tnsaxis:Intercom/KeypadState event

This event will provide you with the information about the different keypad state transitions. The keypad state can have the following values:

Value	Description
`KSM_IDLE`	The idle state, no keypress was detected.
`KSM_PIN_MODE`	PIN code expected and will be processed when the configured number of digits are pressed.
`KSM_MIXED_MODE`	Mixed mode, where a key sequence must be ended with `#` for a PIN code or the call button (C) to place a call.

When there is a transition from one state to another, the device will provide the following event:

Topic: tns1:Device/tnsaxis:Intercom/KeypadState

<tt:MessageDescription IsProperty="true">
  <tt:Source>
    <tt:SimpleItemDescription Name="Source" Type="xs:string"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="State" Type="xs:string"/>
  </tt:Data>
</tt:MessageDescription>

Field name	Type	Description
`Source/Source`	String	The event source, typicall Internal.
`Data/State`	String	The keypad state.