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. Dashboard owns account and service-plan setup; the API portal supports verification, selected assignments, and testing.
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 |
|---|---|
| Active billing cycle + API Access | The location must have a current billed cycle whose charged service plan has API Access enabled. A bound location with no active billing cycle or API Access disabled is ineligible. List Locations omits ineligible locations; location-scoped requests and organization reports that target one return 401 Unauthorized with response code UNAUTHORIZED. |
| 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 | API keys and secrets are created in Dashboard. The secret is available there at creation and remains retrievable later by account owners, account admins, and organization managers from either Dashboard's organization API Keys tab or the API portal's API Keys page. Both interfaces mask the stored secret by default; reveal or copy it only when needed and handle it as a credential. |
| Key bound to the location | A valid key alone is not enough. It must be explicitly associated to each location it will access. The binding remains stored if entitlement later changes, but requests still require API Access in the current charged plan. 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 stored secret is not one-time-only. Account owners, account admins, and organization managers can retrieve it later from Dashboard or the API portal.
Setup steps
- In Dashboard, open the location's Service Plan tab and enable the API Access add-on. If the location already has an active billing cycle, review and confirm the Service Plan quote before continuing.
- 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. The secret is available immediately in the API Keys table; copy it only when needed.
- 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 request requires valid credentials. Use the Authorization header for all integrations and for GET /locations. JSON-body POST, PUT, and DELETE requests may alternatively carry secretKey, but body credentials can appear 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 (limited alternative) | Body authentication with secretKey is available only for JSON-body POST, PUT, and DELETE requests. GET /locations requires the Authorization header. If both are present, Authorization takes precedence. |
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.
Treat the Secret as a credential. Dashboard and the API portal mask it by default, but both make the stored value available to an authorized signed-in account owner, account admin, or organization manager when it is revealed or copied.
Request URL structure
Use the API portal origin as the base URL; the /api/... paths below are relative to that origin, not Dashboard. Every endpoint uses the organization UUID and location-scoped calls also use the location UUID.
| 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 separate from Dashboard and uses the same email and password. Access is limited to authorized account owners, account admins, and organization managers. Use it to verify key status, review location setup, manage transmitter assignments, and test endpoints.
Use the portal's API Keys page to associate and remove location bindings, and use its Locations page to assign and remove existing transmitters from waitlist areas. Use Dashboard to create API keys, change service plans, register transmitters, and modify form fields, guestlists, or area structure.
| Configuration action | Owner interface |
|---|---|
| Associate or remove a key's location bindings | API portal — API Keys page (also available in Dashboard). |
| Assign or remove an existing transmitter from an area | API portal — Locations page. |
| Create API keys or change service plans | Dashboard. |
| Register transmitters or modify guestlists, areas, and form fields | Dashboard. |
4. Portal overview
Monitoring usage and integration health
The Overview page shows rolling 30-day API usage for the selected organization, broken down by request outcome and booking operation type. API key and location filters isolate traffic from a specific integration.
| Counter | What it measures |
|---|---|
| Total Requests | Every API call in the rolling 30-day period across the 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 and failed 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. An organization can have up to three API keys. Keys are created in Dashboard; use the portal to verify status and to associate and remove location bindings that 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 has no active billing cycle or API Access is disabled, the binding remains stored but does not grant entitlement. The portal flags it with a warning, List Locations omits it, and requests that target it return 401 Unauthorized with response code UNAUTHORIZED until the active charged plan grants API Access again.
6. Locations
Reviewing API-enabled setup
The portal Locations page is an organization-level setup view. GET /locations is API-key scoped and returns only eligible bound locations with an active guestlist and at least one active area, so the two lists can differ.
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 booking requests. 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 listed transmitter is eligible to receive pager requests for the area. None assigned means pager requests are skipped. A successful request does not by itself prove physical pager reception. |
| Active badge | Only Active locations process bookings. An inactive location returns an error even if the key is bound to it. |
Use the Locations page to assign and remove existing transmitters from an area. To register or edit a transmitter, reassign a guestlist, modify form fields, or change area configuration, use Dashboard.
GET /locations response
The endpoint returns a Location[]. Each item contains id, name, store_id, and one guestlist object. The guestlist contains areas with id, name, messages, notification options, form.fields, and nullable active transmitter assignments. Form fields include their identifier, title, type, required, active, editable, and visibility settings.
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. Use current field titles and matching value types; unknown or malformed fields may return 400. Refresh local form metadata after Dashboard changes.
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.
Normalize contacts before create
Duplicate detection compares the exact pager_phone_number.value string among active entries in the area. Normalize phone and pager formatting before sending requests.
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, verify the organization, location, guestlist, and area identifiers used by the request.
Use remove states deliberately
Delete state defaults to COMPLETED. Send COMPLETED or REMOVED for terminal outcomes. Delete is idempotent, so HTTP 200 does not prove that every supplied booking ID existed.
Request bodies
| Operation | JSON body |
|---|---|
| Create body | { guestListId, areaId, data, secretKey? }. Save the response id for later operations. |
| Update body | { bookingId, guestListId, areaId, data, secretKey? }. PUT replaces the complete data object, so include every value that must be retained. |
| Delete body | { guestListId, areaId, guests: [bookingId, ...], state?, secretKey? }. state defaults to COMPLETED. |
Responses
| Operation | Response |
|---|---|
| Create | HTTP 201 with the complete created booking object. Its id is the bookingId used by Update and in Delete guests[]. |
| Update | HTTP 200 with the complete updated booking object. |
| Delete | HTTP 200 with { message: "Removed from waitlist" }. Missing IDs are ignored, so the response is idempotent. |
| Error | { message, requestId, code }. Invalid credentials or location scope return 401; inactive accounts or suspended organizations return 403. |
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.
Before the first request, the Response panel remains pending. It changes to the returned status and JSON after Send Request.
Select an API key, choose an endpoint, and fill in every required field before sending. The cURL panel begins as a template and updates from those selections. Treat its authorization value as a credential and do not share it.
| Endpoint | What to confirm after sending |
|---|---|
| List Locations | The response contains eligible locations bound to the selected key with an active guestlist and area. It may be narrower than the portal Locations page. |
| Create Booking | Status 201 with the created booking. Save its id and confirm the entry appears in the correct area. Create does not send a pager notification. |
| Update Booking | Status 200 with the updated booking. Verify all retained data because PUT replaces the complete data object. |
| Remove Booking | Status 200 with a message. The operation is idempotent and does not prove every supplied ID existed. The API has no restore endpoint. |
| 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 use the same date fields and return the same response shape. The organization report may also accept a locations filter; the location report is already scoped by the location UUID in its URL.
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). The range must not be reversed and is limited to 30 days; invalid ranges return 400 BAD_REQUEST. |
| locations | Optional organization-report array. Omit it or send [] for all eligible bound locations. An unbound or ineligible location returns 401 UNAUTHORIZED. |
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 projected using the area's current active, editable fields and current labels. Renamed or deactivated fields can be renamed or omitted from historical output. |
| notifiedDateTimeArray | ACTION_BUTTON notification events only. createdDateTime is serialized as an ISO string; action durations are nested in the corresponding action-button value in data. |
The data object uses the area's current form labels as keys and includes current active, editable fields. Renaming or deactivating a field can rename or omit it from historical report output.
Direct report requests are limited to 30 days and reject larger or reversed ranges with
400 BAD_REQUEST. The Playground always replaces entered dates with today and the previous two calendar dates. Use direct requests for other valid ranges.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 not bound to that location, the location has no active billing cycle, or API Access is disabled in its current charged plan. The response is 401 Unauthorized with code UNAUTHORIZED. Check the binding in the portal and billing in Dashboard.
Location missing from List Locations response
List Locations omits ineligible locations. Confirm that the key is bound, a billing cycle is active, and API Access is enabled in the current charged plan.
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 has the exact same pager_phone_number.value string. Normalize formatting, then update the existing booking or wait for staff to clear it.
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.
No pager alert after Create Booking
Create Booking only adds the entry; it does not send a pager notification. Active area transmitter assignments are used by later staff paging actions.