REST XML Web API V2

Overview

The Integriti REST/XML Web API V2 is the updated REST API Communications Handler. It provides a high-level, stateless, query-based interface for third-party applications to integrate directly with Integriti. Compared to V1, V2 introduces integration modules that group endpoints by use case, an API key authentication model, and a path-prefix system that allows multiple web services on the same port.

Key improvements over V1:

• API key-based authentication instead of license-dependent access
• Modular endpoints grouped by integration type
• Path prefix support for co-hosting multiple services on one port
• Built-in online documentation with interactive request testing
• Postman collection support for easy testing
• Session management with configurable expiry

Prerequisites

• Integriti Professional or higher (REST API V2 is included free)
• Unlock API Key license — one per REST API V2 integration (obtained by contacting Inner Range Sales)
• The API key must be added to the system’s product key via KeyPoint
• Postman (optional, for testing) — https://www.getpostman.com/

Note: The V1 Read, Write, and Control licenses are NOT required for V2. They are only needed for V1 integrations.

Step-by-Step

1. Obtain an API Key

Contact Inner Range Sales to apply for an API key. The Unlock API Key license is generated as part of the application process and can be added to any number of product keys via KeyPoint.

2. Create the Communications Handler

1. Open the Communications Handlers panel from the System tab.
2. Click Add to create a new handler.
3. Give it a Name and add notes.
4. Set Handler Type to REST/XML API v2.

3. Configure Options

Option	Description
Port Number	Port to listen on. Default: 80.
Path Prefix	URL prefix to differentiate services on the same port. Default: restApi.
Disable Response Compression	Responses >10,000 bytes are gzip-compressed unless disabled.
URL To Documentation	Link to online docs; double-click to open (update IP for remote access).
Enable User Management	Enables User Management Integration Module.
Enable Status and Control	Enables Status and Control Integration Module.
Enable Virtual Card Badge	Enables Virtual Card Badge Integration Module.
Enable Review I/O	Enables Review I/O Integration Module.
Session Expiry (min)	Session timeout in minutes (default: 5, range: 1–60).

4. Configure Security

• Use Security:

  • Unchecked — Any client can access the API; actions tunnel through the assigned operator’s permissions.
  • Checked — Clients must authenticate. If an operator is assigned, only that operator can use the API (credential matching). If no operator is assigned, any operator with valid credentials can use the API.

• Security Type (only when Use Security is checked):

  • Basic — Credentials sent as Base64-encoded ID:Password in the Authorization header.
  • HTTPS — Same as Basic, but over a secure channel (recommended). Requires a valid SSL certificate registered with the port via Windows MMC Certificates snap-in.

• Operator — Set the operator for authentication/tunnelling.

5. Windows Configuration

If the Application Server is not running with administrator permissions:

netsh http add urlacl url=http://*:<PORT>/ user=<USER>

If unreachable, clear conflicts:

1. netsh http show urlacl
2. netsh http delete urlacl url=<URL>
3. Re-add: netsh http add urlacl url=http://*:<PORT>/ user=<USER>

API Integration Modules

Each module exposes specific endpoints and can be individually enabled/disabled to limit access.

Module	Purpose
User Management	Query and update user details, permissions, and credentials. Supports bidirectional sync with 3rd party systems.
Review I/O	Generate review in Integriti from 3rd party triggers, or trigger 3rd party actions from Integriti review. Query review and associated entities.
Virtual Card Badge	Trigger a card badge on an Integriti reader from a 3rd party system. Full access control logic applies (permission checks, area updates, review logging, multi-credential support). Supports card data/number or license plate.
Status and Control	Monitor entity status and trigger controller actions (e.g., grant door access, move user to different area).

Using the Online Documentation

Access

Use the URL To Documentation link in the handler settings. If Use Security is enabled, you’ll be prompted for credentials.

Global Headers

After authentication, you’ll be asked to provide the API-KEY request header value. This can be set later via the Global Headers section. The Authorization header is auto-filled from your credentials.

Documentation Structure

• REST API Overview — Enabled modules, session management, authentication, supported headers (Accept, Content-Type).
• Integration Modules — Each module’s page shows readable/writable entities, available routes, and permissions.
• Interactive Testing — Each route page includes a form to fill in parameters and submit test requests directly.

Sending a Request

Example: User Management → Retrieve Specified DB Entity

GET v2/User/{type}/{id}

1. Fill in path parameters: {type} (e.g., “Door”) and {id} (e.g., “c1.d1”)
2. Add query parameters like FullObject=true for complete objects
3. Click Submit to see the result

Testing with Postman

Setup

1. Download the Postman collection and environment files from the online documentation’s Example API Request page.
2. In Postman: File → Import → select both files.
3. Under Environments, open Integriti REST API Test Environment and configure:

Variable	Value
API_KEY	Your integration API key
USER_NAME	Operator username for Basic Auth
PASSWORD	Operator password
HOST_ADDRESS	Server IP and port (e.g., http://192.168.0.43:200)
PATH_PREFIX	Path prefix from handler settings (e.g., restApi)

Sending Sample Requests

1. Set the active environment to “Integriti REST API Test Environment”.
2. Open Collections → Integriti REST API Samples.
3. Select an endpoint (e.g., User Management → Retrieve Specified DB Entity).
4. Headers and URL are pre-populated using environment variables.
5. Click Submit — results appear in the response panel.

Verification

• Open the documentation URL from handler settings — the page should load and show enabled modules.
• Send a test request through the online documentation’s interactive tool.
• Check that the handler shows as Running in the Communications Handlers panel.
• (Optional) Import and run Postman sample requests.

Troubleshooting

Issue	Resolution
401 Unauthorized	Verify API-KEY header is set and correct. Check operator credentials if Use Security is enabled.
Module endpoint not available	Ensure the relevant module is enabled in handler settings (e.g., Enable User Management).
API not reachable	Check Windows port registration (netsh http show urlacl); verify firewall allows the port.
Multiple services port conflict	Assign a different Path Prefix or Port Number to each service.
Session expires too quickly	Increase Session Expiry (min) in handler settings (max 60 minutes).
Compression not working	Ensure Disable Response Compression is unchecked.

Related Pages

• REST XML Web API V1
• Mobile Reader
• Pager Message Sender