REST XML Web API V1

Overview

The Integriti REST/XML Web API V1 is a Communications Handler that hosts a REST/XML-based web service on the Integriti Application Server. It allows third-party applications to integrate with Integriti in a stateless, query-based fashion using standard HTTP methods (GET, POST, DELETE).

The API is organised into four URL paths:

• /DB — Read and write database records
• /Control — Send control commands/actions to entities
• /Review — Access historical review and insert custom review entries
• /Info — System information (host name, version, licenses, server time)

Prerequisites

• Integriti Professional or higher
• Three optional licenses (listed under License Keys → Software Licenses):
  • XML Write 3rd Party Interface
  • XML Control 3rd Party Interface
  • XML Read 3rd Party Interface
• Network access to the Application Server on the configured port
• On Windows systems without administrator permissions: HTTP URL ACL registration (see windows-configuration)

Step-by-Step

1. 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 Web Service.

2. Configure Parameters

• Port — Port to listen on (default is fine, or choose a custom one).
• Use Security:
  • Unchecked — Any client can access the API. If an operator is set, every API action tunnels through that operator’s permissions.
  • Checked — Clients must authenticate. If an operator is set, Integriti validates the authenticated user matches; if no operator is set, any valid operator works.
• Security Type:
  • Basic — Passwords sent in clear text.
  • HTTPS — Secure channel (recommended).
  • Digest — Authentication via Active Directory. Integriti assumes the user is authenticated and looks for the same username among Integriti operators.
• Operator — Select an operator if Security Type is not Basic.

3. Save and Verify

After saving, the handler should show as Running (e.g., “running on port 8888…”). A review message should confirm the AppServer is running the service.

4. Verify API is Operational

Visit the built-in documentation page:

http://[Server_IP]:[Server_Port]/doc/XmlApiDoc.html

The page shows enabled licenses near the top. Interactive examples and full documentation are available at:

http://[Server_IP]:[Server_Port]/doc/XmlApiDoc.html?page=main.html

Documentation pages include:

• [Home] — Basic details on licenses and query string usage
• [Read] and [Write] — Global Controller, Local Controller, State, and Software Valid types
• [Control] — Control capabilities of the XML API
• [Review] — Example of retrieving events
• [Samples] — Sandpit for sending requests

API Usage

Database Read (HTTP GET)

# Get User 1
http://[Server_IP]:[Server_Port]/DB/User?Address=U1

# Find users by first name
http://[Server_IP]:[Server_Port]/DB/User?FirstName=John

# Wildcard search (URL-encoded % for %)
http://[Server_IP]:[Server_Port]/DB/User?Name=%25john%25

# Find users by card number
http://[Server_IP]:[Server_Port]/DB/User?Credentials=1234

# Get all doors
http://[Server_IP]:[Server_Port]/DB/Door

Database Write (HTTP POST)

POST an XML representation of the entity to http://[Server_IP]:[Server_Port]/DB.

Create a new user:

<User>
   <FirstName>John</FirstName>
   <SecondName>Citizen</SecondName>
</User>

Update user and add credential:

<User Address="U5">
   <FirstName>Jim</FirstName>
   <SecondName>Taylor</SecondName>
   <Credentials>
       <CredentialCard>
           <CardType>
               <Ref Type="CardTemplate" Address="TM2" />
           </CardType>
           <CardNumber>1234</CardNumber>
       </CredentialCard>
   </Credentials>
</User>

Tip: Discover XML structures by reading existing entities via GET, or export data from System Designer as .XML.

Database Delete (HTTP DELETE)

DELETE http://[Server_IP]:[Server_Port]/User/U7      # Delete user U7
DELETE http://[Server_IP]:[Server_Port]/AreaList/AL1   # Delete area list AL1

Only global entities (not controller-owned) can be deleted: Door lists, Area lists, Users, Card templates, Telephone numbers, etc.

Control (HTTP GET)

# Lock door D1 on Controller 3
http://[Server_IP]:[Server_Port]/Control/Door?Controller=3&Address=D1&Action=Lock

# Set auxiliary "Master Caution Indicator" to off
http://[Server_IP]:[Server_Port]/Control/Aux?Name=Master%20Caution%20Indicator&Action=off

Query Strings and Encoding

Parameters use standard HTTP query strings (e.g., ?FirstName=John&SecondName=Smith). Characters must be percent-encoded per RFC 3986.

Paging

Multi-result queries return paged data:

<Results Count="474" PageNumber="1" PageSize="25">
  ...
</Results>

Adjust page size and page number via query string parameters.

Windows Configuration

If the Integriti Application Server is NOT running with administrator permissions, explicitly grant port access:

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

Example: netsh http add urlacl url=http://*:80/ user=DOMAIN\user

If the API is still unreachable, remove conflicting registrations:

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

Verification

• Visit http://[Server_IP]:[Server_Port]/doc/XmlApiDoc.html — the documentation page confirms the API is running.
• Check the licenses shown at the top of the documentation page.
• Test a simple GET: http://[Server_IP]:[Server_Port]/Info should return system info.
• Test a database read: http://[Server_IP]:[Server_Port]/DB/Door should return a list of doors.

Troubleshooting

Issue	Resolution
API not reachable	Check Windows port registration (netsh http show urlacl); ensure firewall allows the port.
401 Unauthorized	Verify Use Security settings; check operator credentials and permissions.
License errors	Check licenses under System → License Keys; refresh licenses if the server has internet.
Write operations fail	Ensure the XML Write 3rd Party Interface license is present.
Control operations fail	Ensure the XML Control 3rd Party Interface license is present.
Delete on controller entity fails	Only global entities can be deleted via DELETE.

Related Pages

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