Claim Retrieval and Credentials Validation failure results now use the same problem-details error shape as Insurance Verification, the existing Claims Retrieval error types are now documented in the error reference, and Credentials Validation status polling supports long polling.

What's New​

This aligns Claim Retrieval and Credentials Validation failure results with the problem-details error shape, publishes error reference pages for the existing Claims Retrieval error types, and adds long polling to the Credentials Validation status endpoint.

• Claim Retrieval Status result reshaped to type (URI), title, detail, and optional upstreamErrors[], replacing the old type enum, description, and transient fields.
• Credentials Validation Status result reshaped the same way, replacing its type-only enum object.
• Claims Retrieval error types, already returned as result.type values, are now documented individually in the error reference: Adjusted Claim, Claim Not Found, Claim Procedure Code Not Found, Claim Service Date Not Found, Invalid Claim Search Criteria, Unexpected Intermittent Claim Data, and Unresponsive Payer.
• Credentials Validation Status now supports long polling: send Prefer: wait=<seconds> to hold the connection open for new data, and If-None-Match with the response ETag to receive 304 Not Modified when nothing has changed.

Impact​

Integrations reading the result field from Claim Retrieval Status or Credentials Validation Status failure responses, and any client wanting to reduce polling overhead on Credentials Validation Status. These changes apply to v2 only; v1 endpoints are unchanged.

Why this changed​

Claim Retrieval and Credentials Validation results now follow the same problem-details error shape already used by Insurance Verification, so all v2 result errors look consistent across products.

Changes​

Breaking​

Claims Retrieval​

• GET /v2/claim-retrievals/{correlationId}

Credential Management​

• GET /v2/credentials-validations/{correlationId}

Non-Breaking​

Credential Management​

• GET /v2/credentials-validations/{correlationId}

Upgrade​

1. Update result parsing on Claim Retrieval Status: read result.type, result.title, and result.detail instead of result.type, result.description, and result.transient.
2. Read per-source failures from result.upstreamErrors[].detail on Claim Retrieval Status, if consumed.
3. Update result parsing on Credentials Validation Status: read result.type, result.title, and result.detail instead of the previous type-only object.
4. Read per-source failures from result.upstreamErrors[].detail on Credentials Validation Status, if consumed.
5. Optionally, review the newly documented Claims Retrieval error reference pages listed above; the error types themselves are unchanged.
6. Optionally, adopt long polling on Credentials Validation Status by sending Prefer: wait=<seconds> and If-None-Match to reduce polling overhead.

References​

• Claim Retrieval Status
• Credentials Validation Status
• Adjusted Claim
• Claim Not Found
• Claim Procedure Code Not Found
• Claim Service Date Not Found
• Invalid Claim Search Criteria
• Unexpected Intermittent Claim Data
• Unresponsive Payer

Insurance verification can now return a Plan Not Found error when the member's plan can't be located.

What's New​

Adds a new Plan Not Found error (plan-not-found), returned as a 422 on synchronous insurance verification requests and as a Failed result on the Insurance Verification Webhook, when the member's plan can't be located.

Impact​

Integrations handling insurance verification error responses and webhook failure results.

Why this changed​

Some payer portals can locate the patient but not their plan. Plan Not Found lets that outcome be represented and troubleshot separately from other not-found errors, such as Patient Not Found.

Changes​

Non-Breaking​

Insurance Verification​

• POST /v2/insurance-verifications

• Webhook Insurance Verification Webhook

Upgrade​

No action required. This release is fully backward compatible.

References​

• Insurance Verification Synchronous
• Insurance Verification Webhook
• Plan Not Found (API)
• Plan Not Found (Result)

forwardingEmail is no longer a required field on payer portal registration requests and responses.

What's New​

The forwardingEmail field can now be omitted when creating a payer portal registration, and is no longer guaranteed to be present on registration responses.

Impact​

Integrations that create or list payer portal registrations. No action is required for existing integrations that already send forwardingEmail.

Why this changed​

Some offices don't have an inbox to forward payer portal emails to, so requiring forwardingEmail blocked registrations that don't need email forwarding.

Changes​

Non-Breaking​

Portal Registration & Authentication​

• POST /v2/payer-portal-registrations
• GET /v2/payer-portal-registrations

Upgrade​

No action required. This release is fully backward compatible.

References​

• Create Payer Portal Registration
• List Payer Portal Registrations

Insurance verification responses can now report OutOfServiceArea as a network status.

What's New​

Adds OutOfServiceArea as a new possible value for network status, alongside the existing InNetwork and OutOfNetwork values.

Impact​

Integrations reading network status from insurance verification responses.

Why this changed​

Some payers report that a provider is outside the member's service area, which is distinct from being out-of-network. OutOfServiceArea lets this outcome be represented accurately instead of being reported as OutOfNetwork.

Changes​

Non-Breaking​

Insurance Verification​

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

Upgrade​

No action required. This release is fully backward compatible.

References​

• Get Insurance Verification
• Insurance Verification Synchronous
• Insurance Verification Webhook

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
• Upstream Error