File for the claimant

Use this flow when your application files a complaint and the respondent will answer on the Case Page. Act with claimant authority; a platform credential may coordinate the filing only under its registered authority grant. Keep bearer credentials on your server.

Use the current case view’s availableActions, requirements, and revision for each mutation. The server rechecks authority and deadlines when writing. An idempotency key makes an identical retry recoverable; changing the body under that key is a conflict. Never log show-once party capabilities or invitations.

Claimant acceptance

Deliver the initial hostedAcceptanceUrl to the claimant through an authenticated channel. Supply the required claimantAcceptanceIdentity.email and optional .accountId when preparing. Acceptance requires the matching account ID or a signed-in account with the normalized, verified email (recorded verification or linked Google identity). A person may register first, then match. The external principal ID remains a delegation reference and never authorizes hosted access. The person reviews the claim, requested items, amount, Rules, AI disclosure, procedure and fees, then accepts the exact reviewPacket.termsDigest. The scoped link expires with the draft and is consumed once. It is not returned on preparation replay. GET /api/filings/{id} exposes the packet only to authorized claimant-side callers. Confirm at POST /api/filings/{id}/confirmations as the claimant or platform initiator. Without valid acceptance, acceptance_required returns the digest and, to an authorized claimant caller, a new hosted link. A changed packet requires fresh preparation and acceptance. The invitation is a one-time bearer capability. Until optional designated-email binding is configured, any eligible verified account that receives the link can claim the respondent slot; deliver it only through the intended respondent’s authenticated channel.

Other acceptance proofs

An existing claimant credential may explicitly register method: api_acceptance at /api/v2/authorizations/consents when its registered filing authority binds that exact credential to the packet’s principal. Include filingDraftId, termsHash equal to the packet’s termsDigest, termsVersion: filing-review-packet-v1, and the packet’s scope, parties and transaction. Preserve the acceptance artifact reference and hash. Merely possessing a token or confirming the draft is not acceptance. The SDK exposes acceptFilingPacketV2 for this explicit act.

For wallet acceptance, designate claimantAcceptanceIdentity.walletAddress during preparation. The principal signs the exact reviewPacket.walletMessage; confirmation carries acceptance: { method: "wallet_signature", termsDigest, walletAddress, signature }. The signature binds the public case, exact packet, Rules and disclosure. Wallet control does not select the agent-only procedure.

Standing-grant acceptance is available through a principal-approved OAuth authority grant. Pass acceptance: { method: "standing_grant", grantId, termsDigest } at confirmation. The server checks the delegate tenant, approving account, named filing act, amount cap, transaction scope, current Rules/disclosure, expiry and revocation again at case opening. Standing authority covers ordinary standard procedure only, never Agent-only or compressed clocks. The account receives a durable consent notice. Existing partner file_dispute grants still establish delegated authority separately. See OAuth authentication and delegation.

Historical drafts without a review packet and already-filed cases retain their original consent and replay behavior. New packet acceptance is distinct from respondent joinder and does not create respondent membership or consent.

TypeScript SDK

Save SDK examples at the repository root. Pass the configured PeopleCourtClient from the quickstart, a case ID obtained through your authorized handoff, and a durable idempotency key for each distinct mutation.

import type { PeopleCourtClient, PrepareCanonicalFilingInput,
  CanonicalRecordConfirmationInputPreview } from "./sdk/typescript/src/index.ts";

export async function prepareClaim(client: PeopleCourtClient,
  input: PrepareCanonicalFilingInput, idempotencyKey: string) {
  if (input.intakeMode !== "claimant_initiated") throw new Error("Use claimant intake.");
  return (await client.prepareFilingPreview(input, idempotencyKey)).data;
}

// Call only after the party has reviewed this exact digest and statement.
export async function confirmReviewedRecord(client: PeopleCourtClient,
  caseId: string, reviewed: CanonicalRecordConfirmationInputPreview,
  idempotencyKey: string) {
  const { data: view } = await client.getCasePreview(caseId);
  const action = view.availableActions.find(item => item.code === "confirm_record");
  if (!action || action.requirements.recordDigest !== reviewed.recordDigest ||
      action.requirements.confirmationStatement !== reviewed.confirmationStatement) {
    throw new Error("Refresh the record and obtain confirmation again.");
  }
  return (await client.confirmRecordSummaryPreview(caseId, {
    ...reviewed, expectedRevision: action.expectedRevision,
  }, idempotencyKey)).data;
}

export async function correctOwnRecord(client: PeopleCourtClient,
  caseId: string, correction: string, idempotencyKey: string) {
  const { data: view } = await client.getCasePreview(caseId);
  const { data: result } = await client.correctRecordSummaryPreview(caseId, {
    correction, expectedRevision: view.revision,
  }, idempotencyKey);
  const { data: record } = await client.getRecordSummaryPreview(caseId);
  // A new digest needs a new review. This function does not confirm it.
  return { applied: result.applied, note: result.note, record };
}