Concepts

General Concepts

Concept	Description
Customer	Please contact Zuub Support for your customer credentials
Organization	An organization represents a logical grouping of Clinics
Clinic	A clinic represents a real-world location where patients receive treatments. Data created for a particular clinic, such as payer credentials, is scoped to that clinic and inaccessible to other clinics.

Insurance Verification Concepts

Asynchronous Insurance Verification using Stored Credentials

When making asynchronous insurance verification requests using stored portal credentials (via clinicId and portalId with empty credentials array), the system validates the configuration before processing the request. Validation failures return a 422 error immediately.

Validation Checks

The following validations occur in order:

Check	Error Condition	Resolution
Parameters Present	Missing portalId or clinicId when credentials array is empty	Provide both clinicId and portalId in the request, or include inline credentials
Payer Network Lookup	Payer ID not found in network	Verify the payer ID exists using List Payer Network
Asynchronous Support	Payer does not support asynchronous insurance verification	Check payer's feature map for insuranceVerificationAsynchronous support
Portal Requirements	Portal ID does not meet payer requirements, or portal requires no authentication	Verify portal is listed in payer's asynchronous requirements and requires authentication using List Payer Network
Credentials Exist	No credentials stored for the clinic/portal combination	Create credentials using Create Payer Portal Credentials
Login Method Match	Stored credentials' login method doesn't match portal requirements	Update credentials with correct login method (Native or SSO)
MFA Email Required	Portal requires TwoFactorEmail but stored credentials missing MFA email	Update credentials to include MFA email address
MFA Phone Required	Portal requires TwoFactorSms but stored credentials missing MFA phone	Update credentials to include MFA phone number

Important Notes

• Validation occurs before processing: These checks happen during request validation, not during verification execution
• Early failure detection: Configuration issues are caught immediately rather than during background processing
• Authentication requirement: Only portals that require authentication (not authenticationMethods: None) can use stored credentials
• Portal-specific requirements: Each portal may have different login method and MFA requirements based on the payer configuration

Multi-Factor Authentication (MFA)

Some payer portals require configuration of MFA for enhanced security.

Use the List Payer Network endpoint to discover which authentication methods each portal supports.

SMS-Based MFA

Verification codes sent via text message to a configured phone number

Email-Based MFA

Verification codes sent via email to a configured email address

TOTP (Time-Based One-Time Passwords) MFA

TOTP, more commonly known as "authenticator app" MFA, is an authentication method that generates time-sensitive verification codes. When a payer portal requires TOTP authentication:

• Automatic Configuration: Zuub automatically configures TOTP for portals that require authenticator app-based MFA. No manual setup is required through the API.

Error Types

Name	Description
InactivePatient	The patient is not active
Internal	Generic internal error
InvalidCredentials	Any issue related to credentials (e.g., locked, expired, etc.)
PatientDataSuppressed	The payer website cannot show the patient’s data due to privacy restrictions. A phone call must be placed to get the data.
PatientNotEligible	The patient was found, but the Medicaid or HMO plan is not eligible for the office or provider
PatientNotFound	Patient was not found
ProviderNotFound	Provider was not found
SiteConfiguration	The source is not configured to retrieve insurance verifications
SiteMaintenance	The source is unable to respond at the current time
ThirdPartyAdministrator	The patient's plan information is only available through a third-party administrator
TwoFactorAuthentication	An error encountered during two-factor authentication
TwoFactorAuthenticationConfiguration	The site is not properly configured for two-factor authentication
Upstream	A failure at the source. We include context about the upstream error in this case.

Mismatches

Mismatches report on comparisons of certain insurance verification values between what was sent on the request and what was found on the result. The values that get compared are defined below and included in the response for both synchronous and asynchronous insurance verification requests.

path MismatchPath (string)
Possible values: [
/dependent/dateOfBirth, 
/dependent/firstName, 
/dependent/id, 
/dependent/lastName, 
/plan/group/id, 
/subscriber/dateOfBirth, 
/subscriber/firstName, 
/subscriber/id, 
/subscriber/lastName]

If the value is the same (case-insensitive) on both request and result for a path, no mismatch will be reported for the value. In any other case, a mismatch type will be reported for the value, which will match one of the following scenarios:

type	description
BothPresent	The value was found on both request and result, but the values do not match.
RequestMissing	The value was found in the result, but not in the request; this cannot happen for subscriber values, as these are required in the request.
ResultMissing	The value was found in the request, but not in the result.

Retries

When an asynchronous insurance verification (IV) request fails due to a transient error, the retry system engages, using exponential backoff up to eight (8) attempts, increasing the time between retries up to a maximum of six hours. This system accounts for issues like payer portal outages and maintenance downtime. Rather than developing a retry system, check for updates using the same correlation ID and report errors to Zuub if requests are failing.

Each attempt will send a response to the webhook, regardless of the IV status being Succeeded or Failed. Each response will include retryStatus to indicate whether the IV request will be retried.

Transformers

The Zuub API normalizes data retrieved from third-party sources (e.g., a payer website or an API). We return a TransformerResult for many fields, which represents the result of a normalization attempt. As such, it may be one of three potential cases:

"Missing" Case

While expected, data could not be found. The JSON result is always the same:

{
  "missing": true
}

"Transformed" Case

Data was found and transformed (normalized). For example, an ISO8601 result would be returned as follows:

{
  "final": "2025-01-01T00:00:00.000Z",
  "missing": false,
  "transformed": true,
  "original": ["Jan 1, 2025"]
}

where the original array contains the raw source data.

"Found but not Transformed" Case

Data was found but could not be transformed, or the system could not make sense of the data

{
  "missing": false,
  "transformed": false,
  "original": ["some data"]
}

API Concepts

PATCH Requests

PATCH requests are used to update existing resources. The request body should contain only the properties that need to be updated. Any properties not included in the request body will remain unchanged.

For optional properties, a DELETE token can be passed in place of the value to delete the property. For example:

{
  "propertyName": {
    "token": "DELETE"
  }
}

Webhook

Asynchronous insurance verification makes a webhook call upon completion, sending the verification result. A webhook URL is required and must be configured.

If you need a quick webhook solution, check out ngrok or Webhook Relay.