Fetch setup before sending data
Call List Locations first to get the active area UUID, guestlist UUID, and transmitter status. Hardcoding IDs breaks when managers reconfigure areas in Dashboard.
Connect an external system to LRS Waitlist
The LRS Waitlist API lets an approved external system create, update, and remove waitlist entries and request activity reports — scoped to the locations and organizations the API key is authorized for. Setup happens in Dashboard; verification and testing happen in the API portal.
1. Prerequisites
What must be in place before the first request
API access is an add-on, not a default feature. Every item below must be satisfied before an external system can create a booking or pull a report. Missing any one of them is the most common source of 401 errors during integration.
| Requirement | Where to configure it |
|---|---|
| API Access add-on | Must be enabled on the location's service plan in Dashboard. Without it the location is invisible to the API and all requests for it return 401. |
| Active guestlist and area | The location must have an active waitlist with at least one active area. Bookings target a specific area UUID — there is no default fallback. |
| API key + secret | Generated in Dashboard under the organization's API Keys tab. The Key ID and Secret are both UUIDs. The secret is shown once in Dashboard at creation and is always retrievable from the portal's API Keys page. |
| Key bound to the location | A valid key alone is not enough. It must be explicitly associated to each location it will access. A missing binding returns 401 even with correct credentials. |
| Area form fields known | Booking requests must include the required fields configured for the target area. Fetch the area form from the List Locations endpoint or check Dashboard's Guestlist Form. |
The API key secret is shown once at the moment the key is created in Dashboard. If you did not save it then, open the portal's API Keys page — the secret is masked there by default but can be revealed at any time using the Show control.
Setup steps
- In Dashboard, open the location's Service Plan tab and enable the API Access add-on.
- Confirm the location has an active waitlist assigned and at least one active area.
- In Dashboard, open the organization's API Keys tab and generate a new key. Copy the secret — it is only shown once in Dashboard, but can be retrieved later from the portal's API Keys page.
- Bind the key to each location the external system needs to access, either in Dashboard or in the portal's API Keys page.
- Open the portal's Locations page and note the area UUID for each area the integration will target.
- Use the Playground to send a test Create Booking request and confirm the entry appears in the live Waitlist app.
- Only after a successful end-to-end test, connect the external system to the live API.
2. Authentication
How to authenticate every request
Every API request must include valid credentials. The API accepts two authentication methods. Use the Authorization header method for all new integrations — it is more secure because credentials are not embedded in the request body or visible in application logs.
| Method | How it works |
|---|---|
| Authorization header (recommended) | Base64-encode the string keyId:secret (both are UUIDs) and send the result as the Authorization header on every request. Example: Authorization: Base64("keyId:secret"). Note: this is not standard HTTP Basic Auth — do not include a "Basic " prefix. |
| secretKey in request body (alternative) | Include a secretKey field in the JSON request body containing the secret UUID. The Key ID is not required with this method. Less secure because credentials appear in request logs. |
For the Authorization header method, join the Key ID and Secret with a colon (keyId:secret), base64-encode the result, and send it as the Authorization header on every request: Authorization: <base64>. Do not include a Basic prefix — this API uses a raw base64 value, not the standard HTTP Basic scheme. Both the Key ID and Secret are UUIDs generated in Dashboard.
The Key ID and Secret are available in Dashboard under the organization's API Keys tab. The Key ID is always visible. The Secret is shown once when the key is created in Dashboard — if you did not save it then, open the portal's API Keys page where you can reveal it at any time.
Request URL structure
Every endpoint uses the organization UUID and, for location-scoped calls, the location UUID in the URL path. The area UUID and guestlist UUID are passed in the request body, not the URL.
| Endpoint | Method and URL pattern |
|---|---|
| List Locations | GET /api/{organizationId}/locations |
| Create Booking | POST /api/{organizationId}/locations/{locationId}/bookings |
| Update Booking | PUT /api/{organizationId}/locations/{locationId}/bookings |
| Remove Booking | DELETE /api/{organizationId}/locations/{locationId}/bookings |
| Organization Report | POST /api/{organizationId}/report |
| Location Report | POST /api/{organizationId}/locations/{locationId}/report |
The organization UUID and location UUID come from Dashboard's API Settings tab, accessible from inside any area's Customize view. That tab shows all four UUIDs — organization, location, guestlist, and area — together in one place. The area UUID is also visible in the portal's Locations page when you expand a location card.
3. Portal sign-in
Accessing the API portal
The LRS Waitlist API portal is a standalone web application separate from Dashboard. It uses the same email and password as the Dashboard account. Use it to verify key status, review location setup, manage transmitter assignments, and test endpoints before connecting an external system.
The portal is read-only for configuration — it cannot create API keys, change service plans, or modify form fields. All configuration changes are made in Dashboard. The portal's job is to verify that the setup is correct and to let you test it.
4. Portal overview
Monitoring usage and integration health
The Overview page shows monthly API usage for the selected organization broken down by request outcome and booking operation type. Use the API key and location filters to isolate traffic from a specific integration without leaving the page.
| Counter | What it measures |
|---|---|
| Total Requests | Every API call in the current month across all selected keys and locations. |
| Succeeded | Requests that returned a 2xx response. |
| Failed | Requests that returned a 4xx or 5xx response. |
| Bookings Created / Updated / Removed | Successful booking operations broken down by type. |
| Reports | Successful report generation requests. |
Switching organizations
If the account has multiple organizations, the portal sidebar shows an organization selector. Every page scopes its data to the selected organization. Switching takes effect immediately — no sign-out required.
5. API Keys
Verifying keys and managing location bindings
The API Keys page shows every key for the selected organization: Key ID, masked secret, active status, and bound locations. Keys are created in Dashboard — use the portal to verify status and control which locations each key can access.
The Associate Location section at the bottom of each key card lists eligible locations. Only locations with an active billing cycle and API Access enabled on their service plan appear. Locations that do not meet those requirements are excluded and cannot be associated until corrected in Dashboard.
If a previously bound location lapses its billing or has API Access disabled, the portal flags it with a warning on the key card. Requests from that key to that location will be rejected until the issue is resolved.
6. Locations
Reviewing API-enabled setup
The Locations page is the reference view for confirming which locations, guestlists, areas, and transmitters are active and reachable by the API. Always cross-check this page when the integration returns unexpected results.
Expanding a location card shows the active guestlist name, the area UUID to use in booking requests, and the transmitter assignment for each area. If Transmitters shows None assigned, pager alerts will not fire for bookings in that area even if the request succeeds.
| Field | Why it matters |
|---|---|
| Area UUID | The exact value required in the areaId field of every Create Booking and Update Booking request. A stale or incorrect UUID returns 400. |
| Guestlist name | Confirms which waitlist the API targets. If this does not match the expected waitlist, check the Guestlist workspace in Dashboard. |
| Transmitters assigned | Each transmitter listed broadcasts pager alerts when an entry is notified. None assigned means pager alerts are silently skipped. |
| Active badge | Only Active locations process bookings. An inactive location returns an error even if the key is bound to it. |
The Locations page is read-only. To add a transmitter, reassign a guestlist, or change area configuration, open the location's management tabs in Dashboard.
7. Booking rules
What the external system must respect
The API writes directly into the live Waitlist. These rules prevent data inconsistencies between the external system and what staff see.
Match the area form exactly
Required fields must be present; unknown fields are silently ignored. If a manager changes the form in Dashboard, the external system must refresh its local copy before the next request.
Key must be bound to the location
An active key is not sufficient. It must also be explicitly associated to the location being targeted. A valid key with no binding returns 401.
One active entry per contact per area
If an active entry in the area already uses the same phone or pager number, a new create request for that contact is rejected. Use Update Booking to modify the existing entry instead.
Confirm in Waitlist after every create or update
After a 201 or 200 response, the entry should appear in the live Waitlist app immediately. If it does not, check the portal's recent activity log for the request outcome.
Use remove states deliberately
Removing an entry is irreversible via the API. Pass an explicit state (COMPLETED or REMOVED) that reflects the real outcome — completed service, guest left, or cancellation.
8. Playground
Testing endpoints before going live
The Playground is a built-in API tester. Run every endpoint against a real key and real data without writing any code. Verify that credentials are valid, the area UUID resolves, and a booking appears in the live Waitlist app — all before connecting an external system.
Select an API key, choose an endpoint, fill in the required fields, and click Send Request. The Code snippet panel shows the equivalent curl command with the correct headers and URL. Copy it to test from a terminal or share it with a developer implementing the integration.
| Endpoint | What to confirm after sending |
|---|---|
| List Locations | The response lists the same locations shown on the Locations page. A missing location means the key binding or service plan needs attention. |
| Create Booking | Status 201. Open the live Waitlist app and confirm the entry appears in the correct area. |
| Update Booking | Status 200. Verify the changed field value in the Waitlist app. |
| Remove Booking | Status 200. The entry is gone from the active list. The operation cannot be undone. |
| Organization Report | Status 200 with a nested JSON payload. See the Reports section for the response shape. |
| Location Report | Status 200 with the same payload format scoped to the single location. |
Playground requests hit live data. A Create Booking call adds a real entry to the Waitlist app. Use a test area or remove the entry in Waitlist after testing.
9. Reports
Requesting activity data
Both report endpoints accept the same request body and return the same response shape. The difference is scope: the organization report covers all bound locations (or a filtered subset); the location report covers exactly one location.
Request body
| Field | Description |
|---|---|
| start_date | Required. ISO date string (YYYY-MM-DD). Start of the reporting window. |
| end_date | Required. ISO date string (YYYY-MM-DD). End of the reporting window. If equal to start_date, the window extends to the end of that day. |
| locations | Optional. Array of location UUIDs to include. Organization report only. Omit to include all bound locations. Passing a location UUID not bound to the key returns 401. |
Response shape
The response is a JSON array nested as organization → locations → guestlists → areas → orders. Each order represents one waitlist entry and contains the following fields:
| Field | Description |
|---|---|
| state | Final state of the entry: COMPLETED, REMOVED, or another configured terminal state. |
| createdDateTime | Unix timestamp (ms) when the entry was added to the waitlist. |
| completedDateTime | Unix timestamp (ms) when the entry reached a terminal state. Null if still active at the time of the report. |
| duration | Seconds between createdDateTime and completedDateTime. Zero for entries that were not completed. |
| data | Object keyed by form field label, containing the value recorded for each active, editable field at the time of the entry. |
| notifiedDateTimeArray | Array of notification events for Action Button workflows, including timestamps and durations. |
The data object uses form field labels as keys. Field labels are whatever the area's form designer set — for example, "Guest Name", "Party Size", or "Table #". Only active, editable fields are included. If the form changes after entries are recorded, historical entries retain the label that was active when they were created.
The Playground enforces a fixed 3-day date range for all report requests regardless of the dates entered. This is a portal demo-mode limit, not a server-side restriction. Use it to verify endpoint connectivity and inspect the response shape, then send requests with your own date range directly from your integration.
10. Troubleshooting
Diagnose common integration problems
401 on every request
The Key ID or Secret is wrong, or the key is inactive. Confirm the key is Active in the portal's API Keys page. If the secret is not known, open the portal's API Keys page — the secret is masked by default but can be revealed there using the Show control.
401 on a specific location
The key is valid but not bound to that location. Open the API Keys page in the portal, find the key, and associate the target location.
Location missing from List Locations response
API Access is not enabled on the location's service plan, or the key is not bound to it. Check both in Dashboard and in the portal's API Keys page.
Booking rejected with validation error
A required field for the target area is missing, or a field value does not match the expected format. Open the area's Guestlist Form in Dashboard to see the current configuration.
Booking returns 200 but entry missing in Waitlist
The request used the correct area UUID but the wrong organization or location UUID in the URL path. Recheck all three IDs from the Locations page in the portal.
Duplicate entry rejected
An active entry in the area already uses the same phone or pager number. Use Update Booking to modify it, or wait for staff to clear the existing entry.
Report returns empty results
Confirm the date range contains activity and that the key is bound to at least one location. If the key has no bound locations, the org report returns 401 rather than empty data.
Pager alerts not firing after a create
The area has no transmitter assigned. In Dashboard, open the area's Settings tab and assign a registered transmitter. The booking still lands in Waitlist — only the pager broadcast is skipped.