Drive the ClaimCenter claims lifecycle through Cloud API and survive the failure modes that derail naive automation. This is the workflow used by FNOL portals, IVR claims intake, partner-of-record APIs, and reserve-setting jobs. Assumes guidewire-install-auth provides the bearer token and guidewire-sdk-patterns provides the retrying client with checksum round-trip.
Five production failures this skill prevents:
Duplicate FNOL from multi-source intake — the same loss event is reported by the caller, the claimant, and the broker; without dedup logic three claims land on the same loss with three reserves.
Payment before reserve — code creates a payment without first setting a reserve in the matching cost category; API returns 422 reserve-required.
Authorization-tier violation — an integration with payment role cc.payment.write attempts a payment above its authorization limit; API returns 422 authorization-required and the payment lands in pending-approval.
Premature settlement — claim closed before all open reserves are zeroed or all open activities resolved; reopens compound work and generate audit findings.
— late-arriving evidence on a closed claim creates a new claim with a different number, breaking the loss-event continuity downstream finance and analytics depend on.
Reopen vs. new claim confusion
Prerequisites
A working auth + SDK layer per guidewire-install-auth and guidewire-sdk-patterns
Cloud API roles cc.claim.write, cc.reserve.write, cc.payment.write assigned per least privilege; payment authorization tier matches the integration's expected payment range
Knowledge of the carrier's loss-cause code list (AUTO, PROPERTY, WORKERSCOMP, etc.) and cost-category configuration (body, parts, medical, legal)
Before creating a claim, check whether one already exists for the same loss event. The dedup key combines policy, loss date, loss cause, and the reporting party.
The dedup window is loss-cause-specific. For AUTO, same-day same-cause is almost certainly the same event. For PROPERTY, weather events can produce multiple legitimate same-cause same-day claims across distinct locations — extend the dedup key with the loss-location ZIP for that line.
2. Reserve setting before any payment
Reserves communicate the carrier's expected outflow per cost category. The Cloud API enforces "reserve before payment" — payments without a matching reserve return 422 reserve-required.
Reserve adjustments (raise/lower) use PATCH on the reserve resource; checksum round-trip applies. Lowering a reserve below cumulative payments returns 422 — fix payments first or use a reserve transfer.
3. Payments with authorization-tier handling
The integration's authorization tier is configured per Service Application in GCC. A payment that exceeds the tier does not error — it lands in Status: PendingApproval and waits for a supervisor:
Do not poll the payment for completion. Subscribe to the App Event for payment-status-change and react asynchronously — this is covered in guidewire-webhooks-integrations.
4. Settlement with completeness gates
A claim should only close when every exposure has either been paid in full, denied, or has reserves zeroed; and every required activity (subro decision, salvage decision, supervisor sign-off) is completed.
async function isReadyToSettle(claimId: string): Promise<{ ready: boolean; blockers: string[] }> {
const claim = await getClaim(claimId, "exposures,activities,reserves");
const blockers: string[] = [];
for (const reserve of claim.included.reserves) {
if (reserve.attributes.status.code === "Open" && reserve.attributes.amount.amount > 0) {
blockers.push(`reserve ${reserve.id} is ${reserve.attributes.amount.amount} open`);
}
}
for (const activity of claim.included.activities) {
if (activity.attributes.required && activity.attributes.status.code !== "Completed") {
blockers.push(`activity ${activity.id} (${activity.attributes.subject}) not completed`);
}
}
return { ready: blockers.length === 0, blockers };
}
Only call the close endpoint when isReadyToSettle returns ready: true. Premature closure works but creates audit findings and forces reopens.
5. Reopen vs. new claim
Late-arriving evidence on a closed claim is almost always the same loss event. Reopen the existing claim rather than creating a new one — claim numbers must remain stable for the underlying loss event so finance, analytics, and regulatory reporting continue to roll up correctly.
payment exceeds the integration's authorization tier
not an error path — the payment lands in PendingApproval; subscribe to status-change event
422 reserve-below-payments on reserve PATCH (lower)
trying to lower a reserve below the cumulative paid amount
reverse a payment first, or use a reserve transfer endpoint
409 Conflict on claim PATCH
concurrent edits
use patchResource() from guidewire-sdk-patterns
422 close-blocked on close endpoint
open reserves or incomplete required activities
run isReadyToSettle() before calling close
Two claim numbers exist for the same loss event
dedup logic is missing or the dedup key is too narrow
extend the key (add ZIP for property lines, add VIN for auto)
Reopen endpoint returns 422
claim is too old (carrier-configured retention)
new claim is the only path; document the loss-event linkage in the new claim's notes
Late evidence created a new claim instead of reopening
code did not check existing-claim status before creating
always check getClaimByNumber() before createClaim() for late events
For deeper coverage (subrogation tracking, salvage handling, recovery payments, multi-claimant scenarios, fraud-flagging on intake), see implementation guide and API reference.
See Also
guidewire-install-auth — bearer token and scope assignment
