Skip to main content

Overview

Listo is Auditdata's hearing-screening platform. Locations run the Listo iPad app to perform short screenings; results are submitted to the Listo backend and made available to your management system through this API.

This page defines the five concepts that show up everywhere in the rest of the documentation. Read them once and the rest of the site will make sense.

Tenant​

A Tenant is the externally-facing identity Auditdata issues credentials to. Each tenant corresponds to an organization that runs the Listo iPad app and submits screenings, and is identified by a TenantId (a UUID).

When Auditdata onboards your management system, we link one or more TenantIds to your account. For each linked tenant you get one (client_id, client_secret) pair; tokens minted with that credential pair are scoped to exactly that tenant. Service Bus delivery is configurable per tenant — see Queue for the default (one queue per tenant) and the optional shared-queue mode.

Internally, Auditdata also refers to these entities as "Customers" in some legacy systems. Integrating systems interact with them exclusively via the Tenant identity through this API.

Session​

A Session is one completed hearing screening for one patient on one device. Sessions are stored in Listo's database and identified by a numeric id (assigned by the database when the session is persisted).

A session contains:

  • The patient's identifying information (name, contact, demographics).
  • The location and device context (office, device, transducer).
  • The audiometric results — left/right ear thresholds at 250–8000 Hz, plus derived "some hearing loss" / "significant hearing loss" overlays.
  • Consent flags captured during the test.
  • Timestamps for when the test was performed, persisted, and exported.

The full schema is documented in Screening completed and Data schema reference.

Event​

An Event is a CloudEvents 1.0 message that Listo emits to Service Bus when a session is submitted. The event body (data) contains the full session payload.

In v1, exactly one event type is emitted:

com.auditdata.listo.screening.completed.v1

Events are pushed to the dedicated Service Bus queue for the session's tenant. The Sessions API exposes the same screenings via REST — but without the CloudEvent envelope; see Sessions API below.

Queue​

A Queue is a dedicated Azure Service Bus queue. Auditdata provisions queues during onboarding and hands you one listen-only SAS connection string per queue. The queue topology is configurable per tenant:

  • Default — dedicated queues. One queue per tenant. Each queue carries events for exactly one tenant, and every event on the queue has the same data.tenantId. If your integrating system is linked to N tenants under this default, you receive N queues and N connection strings.
  • Optional — shared queue. At onboarding you can request that two or more of your tenants route to a single shared queue instead. A shared queue carries events for the configured subset of your tenants — never anyone else's. Events from different tenants are interleaved on the queue; the consumer reads data.tenantId to discriminate.

The choice is per-tenant: an integrating system may have some tenants on dedicated queues and some on a shared queue, in any combination. Both topologies use the same CloudEvent payload and the same data.tenantId discriminator.

  • The queue uses structured CloudEvents binding: each Service Bus message body is a UTF-8 JSON document containing the entire CloudEvent envelope.
  • Delivery is at-least-once. Use the CloudEvent id to deduplicate.

Sessions API​

The Sessions API is a single REST endpoint, GET /v1/tenants/{tenantId}/screenings, that returns screening objects in time-range pages — the same screenings that arrive on Service Bus, returned directly without the CloudEvent envelope wrapper. Each token is scoped to exactly one tenant; the {tenantId} in the path must equal the token's tenant_id claim. To query a different tenant, mint a token with that tenant's credentials. Use the Sessions API to:

  • Backfill events you missed while your consumer was offline.
  • Reprocess a window after a downstream bug was fixed.
  • Seed historical state when first integrating.

The Sessions API is paginated with self-describing time-based next-page URLs and is bound by OAuth 2.0 client credentials. See the REST reference.

How the pieces fit together​

The iPad submits a completed screening. Within the same backend request that persists the session, Listo also publishes a CloudEvent to the Service Bus queue for that tenant. The queue and the database stay in sync — anything you can fetch from /v1/tenants/{tenantId}/screenings is also something that was (or will be) on the queue for that tenant.

The full architecture, including the publication path, is in Architecture.

What we provision for you​

When you onboard, Auditdata sets up:

  1. Service Bus queues — one per tenant by default; optionally a shared queue for multiple tenants. Each queue is created in our Azure subscription with a listen-only SAS authorization rule so you can connect, receive, and acknowledge — but cannot send or manage. Default: one queue per tenant; each queue carries events for exactly one tenant. Optional: at onboarding you can ask us to route two or more of your tenants to a single shared queue. Mix-and-match is fine — some tenants on dedicated queues, some on a shared queue, in any combination.
  2. One SAS connection string per queue. Each is a single-line secret of the form Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=…;SharedAccessKey=…;EntityPath=<queue>. With shared queues the count is N queues → N connection strings, where N may be less than your tenant count.
  3. One OAuth (client_id, client_secret) pair per tenant. Used with the client_credentials grant to mint bearer tokens for the REST API; each token is scoped to the single tenant the credentials were issued for. N tenants → N credential pairs. See OAuth overview and Obtaining tokens.
  4. The two endpoint URLs you'll need:
    • The OAuth token endpoint (https://auth.<environment>/oauth/token).
    • The REST API base URL (https://api.<environment>).