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.

• Code Generation: Use the Generate Payer Portal TOTP Code endpoint to retrieve codes when needed.

Procedure Codes

The procedureCodes field controls which dental procedure codes are included in the insurance verification response.

• Empty array ([]): Returns results for the standard procedure codes listed below.
• Codes provided: Returns results for the standard procedure codes plus the additional codes specified in the request.

Standard Procedure Codes

D0120 D0210 D0220 D0272 D0274 D0330 D0367 D0431 D1110 D1120 D1206 D1208 D1351 D1510 D2390 D2393 D2630 D2643 D2740 D2750 D2790 D2929 D2930 D2932 D2933 D2934 D2950 D3120 D3220 D3230 D4341 D4355 D4381 D4910 D5110 D5670 D5751 D6010 D6240 D7140 D7210 D7230 D7240 D7953 D8010 D9222 D9223 D9230 D9248 D9310

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.