Skip to main content

Integration Guidance: Insurance Verification

This guide walks you through integrating with Zuub's Insurance Verification (IV) API, from initial setup to submitting your first verification request. It's written for developers building the integration and product managers overseeing the process.

Before You Begin: Sandbox & Test Data​

Zuub provides sandbox access for integration development. You can request access and obtain API keys via this form.

Important: To receive meaningful verification results, you must submit requests with real patient and insurance data. Sample data shown in the API reference documentation is redacted and for illustrative purposes only; it cannot be used to generate actual results.

How Zuub IV Works​

Zuub automates insurance eligibility verification by connecting to payer systems (directly or via portals) on behalf of dental clinics. Instead of staff manually logging into portals, Zuub stores each clinic's payer portal credentials and submits verification requests programmatically.

There are two verification modes:

  • Asynchronous (recommended): Submit a request and receive results via webhook when complete. Typically results in the greatest depth and breadth of data.
  • Synchronous: Submit a request and receive results in the same API response.

Core Data Model​

Before making any API calls, it helps to understand how Zuub organizes data. There are four key entities, and they nest hierarchically:

Entity Hierarchy

Customer represents your company. Zuub provides your customerId during onboarding.

Organization represents a dental practice or business entity, typically the legal entity that operates one or more clinics. You create organizations using the Create Organization endpoint, which returns an organizationId.

Clinic represents a physical office location within an organization. A single organization may operate multiple clinics. You create clinics using the Create Clinic endpoint, which returns a clinicId.

Credentials are payer portal usernames and passwords stored at the clinic level. Each clinic needs credentials for each payer portal it verifies against. Zuub securely stores and manages these credentials; your integration creates and retrieves them via the API, and portal authentication is handled by Zuub.

Step-by-Step Setup​

Step 1: Create Your Organization​

Using the customerId provided by Zuub, call Create Organization to set up your first organization.

POST /organization

This returns an organizationId you'll use in subsequent calls.

Step 2: Create a Clinic​

Using the organizationId from Step 1, call Create Clinic to create a clinic within that organization.

POST /clinic

This returns a clinicId.

Step 3: Discover Supported Payers​

Call List Payer Network to retrieve the catalog of supported payers. For each payer you plan to integrate with, you'll need to confirm:

  • Async support, whether the payer supports asynchronous verification (recommended for production)
  • The portalId, required for portal registration in Step 4

The Payer Network page documents the full feature support model, authentication methods, login methods, and requirement types for each payer. Review it to understand what each payer requires for submitting verification requests.

Note: Payer discovery is required before portal registration; you'll need the portalId to proceed with Step 4.

Step 4: Register on Payer Portals​

Before storing credentials in Zuub, you need to register accounts on each payer portal your clinic will use. Zuub generates the registration details for you.

4a. Call Create Payer Portal Registration with the portalId. Zuub provisions a registeredEmail and, depending on the portal's authentication method, may also provision a registeredPhoneNumber. See Create Payer Portal Registration for full details on request parameters and response fields.

4b. Navigate to the payer portal directly and create an account using the registration details provided by Zuub. Set a password during registration; you'll store this in Zuub in the next step.

Step 5: Store Credentials in Zuub​

After registering on each payer portal, return to Zuub to store the credentials. Call Create Payer Portal Credentials with the credential details for that clinic and portal. See Create Payer Portal Credentials for the full request schema.

Zuub securely stores and manages these credentials and uses them for all future IV requests for that clinic and payer.

Recommended: Before storing, you can validate that credentials work by calling Credentials Validation Request. This is an asynchronous process; use the correlationId from the response to poll Credentials Validation Status for results. This helps catch issues such as incorrect passwords or expired portal accounts before they're stored.

Credential Management​

Zuub recommends using credential storage (Steps 4–5 above). When submitting a verification request, supply the clinicId and portalId; Zuub looks up the stored credentials for that clinic and portal combination. This simplifies your verification requests and centralizes credential management within Zuub.

Alternatively, credentials can be passed directly in the credentials object of each verification request. Review the Insurance Verification Asynchronous and Insurance Verification Synchronous endpoint documentation for details on the request fields.

Submitting a Verification Request​

You don't need to complete all setup steps before submitting your first verification. We recommend running two workstreams in parallel:

Parallel Workstreams

Workstream 1, Setup: Create your organization, clinics, and register/store credentials for each payer portal (Steps 1–5 above).

Workstream 2, First verification: Submit a synchronous verification request early to see real results and familiarize yourself with the response schema. Synchronous requests don't require webhook configuration, so you can start testing as soon as you have credentials stored for at least one payer.

This approach gets your team to a real IV result faster and helps developers understand the data model while the broader integration is still being built out.

Synchronous Verification​

POST /insurance-verifications

Submit the request and receive the result in the same response. No webhook configuration required.

See Insurance Verification Synchronous for the full request schema and response fields.

POST /insurance-verification-requests
  1. Submit the request with patient and insurance details.
  2. Zuub queues the verification and processes it in the background.
  3. Results are delivered via webhook when complete.

Make sure you've configured your Webhook Configuration to receive results. Asynchronous verification is recommended when available. Discuss with your Zuub contact to confirm which mode applies to each payer in your network.

See Insurance Verification Asynchronous for the full request schema and response fields.

What's Next​