Skip to main content

Implementation Guide

Make all External App API calls from your backend. Include these headers:

Content-Type: application/json
SessionTokenID: YOUR_EXTERNAL_APP_SESSION_TOKEN

1. Validate the pairing code​

Send the code provided by the customer to Validate external app pairing code.

{
  "PairingCode": "ABC123"
}

Continue only when the response has success: true and data: true. Pairing codes should be submitted once and must not be stored in logs, analytics, or client-side persistence.

2. Retrieve linked sites​

Call Get external app linked sites. Each returned site contains a stable numeric ID and a display Name.

Persist the site ID with your local customer or location record. Use the name for display only.

3. Retrieve linked entry points​

For each site, pass its ID to Get external app linked entry points:

GET /GetLinkedEntryPoints?SiteID=12345

Store each entry point's ID, Name, and CanIssueRemoteCommand value. Hide or disable remote controls when CanIssueRemoteCommand is false.

4. Generate a remote command​

Call Generate remote command with the chosen entry-point ID. To unlock an entry point:

{
  "EntryPointID": 12345,
  "Command": "unlock"
}

Store the returned CommandID. A successful submission means the command was accepted for processing, not that the entry point has completed it.

warning

Do not retry command creation automatically after an ambiguous network failure. First determine whether the original request created a command to avoid issuing the physical action twice.

5. Check command status​

Pass the command ID to Get external app command status:

GET /GetCommandStatus?CommandID=00000000-0000-0000-0000-000000000000

The response includes a numeric Status and a human-readable StatusDescription. Use the documented status values agreed during partner onboarding, and display the description when reporting a failure.

Poll at a bounded interval and enforce a timeout in your application. Do not poll indefinitely.

Keep local data synchronized​

Re-fetch linked sites and entry points after pairing and on a periodic schedule. Remove access to resources that are no longer returned by the API, and update names and command capabilities from the latest response.