Account Setup, Authentication, Claims Retrieval, Configuration, Credential Management, Insurance Verification, Payer Network & Portals, Portal Registration & Authentication: v1 → v2 migration

The v2 API reference is now live, with a complete error message reference and error responses standardized on the RFC 9457 problem+json format. Insurance verification gains a new Partial outcome and several benefit schema additions, alongside changes to failure results and coinsurance that require updates when migrating from v1.

What's New​

This release publishes the v2 API reference and standardizes how errors are represented across the API, and it extends the insurance verification contract with a new outcome and richer benefit data.

• API reference with a category-grouped error message reference for API and webhook errors (including whether each is retryable), with error responses standardized on RFC 9457 problem+json (type, title, status, detail) and validation failures now returned as 422 across more endpoints.
• New Partial status added for insurance verification outcome on both the Get Insurance Verification and the Insurance Verification Webhook, returning partially-retrieved data with contexts that explain the gaps. For example, payers like Denti-Cal, which require checking multiple portals, may return a Partial status with contexts explaining which portal or data point couldn't be retrieved.
• Provider network participation, benefit maximum carryover amounts, and a carry-over disclaimer type added to insurance verification results. Payer coverage for these fields is expanding over time. Availability depends on whether a given payer's portal exposes this data, so these fields may not be populated for every payer yet.
• New assignment field added to the plan in InsuranceVerificationV3 result, identifying the office and/or provider the plan is assigned to. Applies to plans that restrict coverage to an assigned office or provider, such as HMO, Medicaid, and Medicare. Like other additive fields, availability depends on whether the payer's portal exposes this data.

Impact​

Affects any client moving from v1 to v2. Because v1 and v2 run side by side, existing v1 integrations are unaffected until they migrate, but v1 is retired on December 31, 2026, so every v1 integration must move to v2 before that date.

When migrating, every request must move from /v1/* to /v2/*, and clients must parse error bodies as RFC 9457 problem+json (including 422 validation responses with a field-level errors[] array) rather than the legacy error shapes.

Insurance verification integrations additionally must handle the new Partial status and the reshaped failure result, and read coinsurance percentage.final as a range. The additive benefit fields require no action to keep working.

Why this changed​

• Error responses were standardized on the RFC 9457 problem-details format for consistency across the v2 API.
• The new Partial status lets insurance verification return the benefits it could retrieve, with contexts explaining what was missing and why, instead of failing the entire request when only some data is unavailable.

Changes​

The following summarizes the API contract as it moves from v1 to v2, grouped by resource. Because v1 and v2 run side by side, none of this affects existing v1 integrations.

All API Endpoints​

Account Setup, Credential Management, Portal Registration & Authentication​

• GET /v2/organizations/{organizationId}
• GET /v2/organizations/{organizationId}/clinics
• GET /v2/clinics/{clinicId}
• GET /v2/clinics/{clinicId}/portals/{portalId}/credentials
• GET /v2/emails
• GET /v2/sms-messages
• GET /v2/payer-portal-registrations/{correlationId}/emails
• GET /v2/payer-portal-registrations/{correlationId}/sms-messages

• POST /v2/organizations
• GET /v2/organizations/{organizationId}/clinics
• GET /v2/customers/{customerId}/organizations
• POST GET PATCH /v2/clinics/{clinicId}/portals/{portalId}/credentials

Insurance Verification​

• GET /v2/insurance-verifications/{correlationId}
• Webhook Insurance Verification Webhook

• POST /v2/insurance-verifications
• POST /v2/insurance-verification-requests

Claims Retrieval​

• POST /v2/claim-retrieval-requests

Upgrade​

1. Repoint every request from /v1/* to /v2/*. The resource set is unchanged; only the version prefix moved.
2. Parse all error bodies as RFC 9457 problem+json (type, title, status, detail). See the Error Reference for the full list of error types:
   • Treat type as a URI, not a token like Internal.
   • Read upstream failures from upstreamErrors[] (was details).
3. Update failure-response parsing on Get Insurance Verification and the Insurance Verification Webhook:
   • Replace result.details.code and result.details.message with result.type, result.title, and result.detail.
   • Read per-source failures from result.upstreamErrors[].detail. See the Upstream Error webhook example.
4. Handle 422 validation responses: read the errors[] array for field-level failures, each with:
   • field: the parameter that failed validation.
   • message: a human-readable description.
   • code: a machine-readable reason (e.g. invalid_value).
5. Read coinsurance percentage.final as an object with numeric start and end, not a string.
6. Handle the new Partial status on Get Insurance Verification and the Insurance Verification Webhook: read result.data and the new result.contexts.
7. Stop relying on error codes that v2 removed:
   • 422 on Get Insurance Verification.
   • 400, 404, and 409 responses dropped from the organization, clinic, and credential endpoints.
8. Optionally, consume the new verificationProvider field on InsuranceVerificationV3 result, the provider used to look up benefits. See Get Insurance Verification for the full schema. Includes:
   • firstName, lastName, middleName, address, taxId.
   • Network participation.status (Participating and Non-Participating).
9. Optionally, consume the new assignment field on the InsuranceVerificationV3 result's plan (result.plan.assignment), identifying the office and/or provider the plan is assigned to.

References​

• Error Reference
• Get Insurance Verification
• Insurance Verification Webhook
• Webhook Upstream Error