POSTpartial

Prepare an account-owned filing and its hosted acceptance link

Account branch, selected by a People's Court account access token with filings:write. It creates an immutable account-owned standard-procedure draft and its review packet through the shared filing preparation service, resolving the claimant from the authenticated account. No partner tenant, partner credential, consent artifact or representative appointment is created. Typed requested relief, exact minor-unit money, pinned Rules and disclosure, fee prerequisites and the deferred respondent consent rule are preserved. The response carries the packet summary and a hosted acceptance link whose one-use secret is returned once and never stored in the idempotency replay body. Idempotency is the caller's key scoped to the authenticated account, not to a token: the same key with the same body replays the stored draft, and the same key with a different body is refused with idempotency_conflict. The partner branch is unchanged.

/api/filingsprepareAccountFiling

Authentication and authority

Use one listed account-session, scoped OAuth, or partner credential alternative. Account tokens retain the approving account’s authority. Cookie-authenticated writes require same-origin authorization. Alternatives are OR; schemes in one alternative are AND.

AccountOAuth

Account tokens authorize only their approving account and case scope. S256 PKCE is mandatory on the code flow. Explicit reacceptance is required after Rules/disclosure changes.

Parameters

NameLocationRequirementSchema
Idempotency-KeyheaderRequired{"type":"string","minLength":8,"maxLength":200}

Request body

Required request body.

application/json

{
  "$ref": "#/components/schemas/AccountFiling",
  "type": "object",
  "description": "Canonical filing preparation input for a People's Court account token. The claimant is resolved from the authenticated account and is never supplied here; no partner tenant, credential, consent artifact or representative appointment participates. Agreement to arbitrate and the attestation of truthfulness are made by the person on the hosted acceptance page, so they are not request fields.",
  "required": [
    "parties",
    "summary",
    "claim",
    "declaration"
  ],
  "additionalProperties": false,
  "properties": {
    "procedure": {
      "type": "string",
      "const": "standard",
      "description": "Only the standard procedure is available here. The agent-only procedure requires each side's express acceptance of the exact procedure through its own endpoint."
    },
    "parties": {
      "type": "object",
      "required": [
        "respondent"
      ],
      "additionalProperties": false,
      "properties": {
        "claimant": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "principalKind": {
              "type": "string",
              "enum": [
                "individual",
                "organization",
                "autonomous_agent"
              ],
              "description": "Optional assertion that must match the authenticated account's own principal kind."
            }
          }
        },
        "respondent": {
          "type": "object",
          "required": [
            "name",
            "principalKind"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "maxLength": 200
            },
            "principalKind": {
              "type": "string",
              "enum": [
                "individual",
                "organization"
              ]
            },
            "email": {
              "type": "string",
              "maxLength": 320
            },
            "emailIsProper": {
              "type": "boolean",
              "const": true,
              "description": "Required with an email address. The claimant attests this is the defendant's current address for the transaction or notices."
            },
            "emailSource": {
              "type": "string",
              "enum": [
                "claimant_attested",
                "agreement",
                "notice_designation"
              ]
            }
          }
        }
      }
    },
    "summary": {
      "type": "string",
      "maxLength": 20000
    },
    "backgroundFacts": {
      "type": "string",
      "maxLength": 20000
    },
    "governingLaw": {
      "type": "string",
      "enum": [
        "platform_native",
        "common_law_contract",
        "custom_terms",
        "english_law",
        "singapore_law",
        "new_york_law",
        "delaware_law"
      ]
    },
    "customTerms": {
      "type": "string",
      "maxLength": 20000
    },
    "claimAmount": {
      "$ref": "#/components/schemas/FiatMoney",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "currency",
        "minorUnits"
      ],
      "properties": {
        "currency": {
          "type": "string",
          "const": "USD"
        },
        "minorUnits": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,77})$"
        }
      }
    },
    "remedialJurisdictionOptIn": {
      "type": "boolean"
    },
    "claim": {
      "type": "object",
      "required": [
        "statement",
        "requestedItems"
      ],
      "additionalProperties": false,
      "properties": {
        "statement": {
          "type": "string",
          "maxLength": 20000
        },
        "requestedItems": {
          "type": "array",
          "minItems": 1,
          "maxItems": 3,
          "description": "One typed item per kind. A monetary item requires a positive claimAmount; a declaration must begin \"Declare that\".",
          "items": {
            "type": "object",
            "required": [
              "kind",
              "text"
            ],
            "additionalProperties": false,
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "monetary",
                  "declaratory",
                  "order"
                ]
              },
              "text": {
                "type": "string",
                "maxLength": 4000
              }
            }
          }
        }
      }
    },
    "declaration": {
      "type": "object",
      "required": [
        "declarantName",
        "declarantCapacity",
        "executionLocation"
      ],
      "additionalProperties": false,
      "properties": {
        "declarantName": {
          "type": "string",
          "maxLength": 200
        },
        "declarantCapacity": {
          "type": "string",
          "maxLength": 200
        },
        "executionLocation": {
          "type": "string",
          "maxLength": 200
        }
      }
    }
  }
}

Responses

201

The account-owned filing draft, its review packet and the one-use hosted acceptance link.

application/json

{
  "type": "object",
  "required": [
    "data",
    "requestId"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AccountPreparedFiling",
      "type": "object",
      "description": "An immutable account-owned filing draft and its review packet.",
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "account-filing-v1"
        },
        "filingId": {
          "type": "string"
        },
        "procedure": {
          "type": "string",
          "const": "standard"
        },
        "schedule": {
          "type": "object",
          "required": [
            "profile"
          ],
          "properties": {
            "profile": {
              "type": "string",
              "const": "standard"
            }
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "awaiting_acceptance",
            "accepted"
          ]
        },
        "owner": {
          "type": "object",
          "required": [
            "accountId"
          ],
          "properties": {
            "accountId": {
              "type": "string"
            }
          }
        },
        "draftDigest": {
          "type": "string"
        },
        "termsDigest": {
          "type": "string"
        },
        "expiresAt": {
          "type": "string"
        },
        "acceptance": {
          "type": "object",
          "required": [
            "required",
            "method",
            "recorded"
          ],
          "properties": {
            "required": {
              "type": "boolean",
              "const": true
            },
            "method": {
              "type": "string",
              "const": "hosted_clickwrap"
            },
            "recorded": {
              "type": "boolean"
            },
            "acceptedAt": {
              "type": "string"
            }
          }
        },
        "reviewPacket": {
          "$ref": "#/components/schemas/AccountFilingReviewPacket",
          "type": "object",
          "description": "The exact packet the person reviews and accepts on People's Court. It contains only prepared typed filing fields; no capability, token or private preparation note enters it.",
          "properties": {
            "schemaVersion": {
              "type": "string",
              "const": "account-filing-review-packet-v1"
            },
            "draftId": {
              "type": "string"
            },
            "caseId": {
              "type": "string",
              "description": "Case identity reserved for this packet."
            },
            "draftDigest": {
              "type": "string"
            },
            "termsDigest": {
              "type": "string"
            },
            "acceptanceStatement": {
              "type": "string"
            },
            "parties": {
              "type": "object",
              "required": [
                "claimant",
                "respondent"
              ],
              "properties": {
                "claimant": {
                  "type": "object",
                  "required": [
                    "principalId",
                    "name",
                    "principalKind"
                  ],
                  "properties": {
                    "principalId": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "principalKind": {
                      "$ref": "#/components/schemas/CanonicalPrincipalKind"
                    }
                  }
                },
                "respondent": {
                  "type": "object",
                  "required": [
                    "name",
                    "principalKind"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "principalKind": {
                      "$ref": "#/components/schemas/CanonicalPrincipalKind"
                    },
                    "noticeAddress": {
                      "type": "object",
                      "required": [
                        "email",
                        "source"
                      ],
                      "properties": {
                        "email": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "claimant_attested",
                            "agreement",
                            "notice_designation"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "claimantIdentity": {
              "type": "object",
              "required": [
                "accountId",
                "email"
              ],
              "properties": {
                "accountId": {
                  "type": "string"
                },
                "email": {
                  "type": "string"
                }
              }
            },
            "agentOfRecord": {
              "type": "string"
            },
            "claimSummary": {
              "type": "string"
            },
            "claimStatement": {
              "type": "string"
            },
            "requestedItems": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "id",
                  "kind",
                  "text"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "monetary",
                      "declaratory",
                      "order"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "amount": {
                    "$ref": "#/components/schemas/FiatMoney",
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "currency",
                      "minorUnits"
                    ],
                    "properties": {
                      "currency": {
                        "type": "string",
                        "const": "USD"
                      },
                      "minorUnits": {
                        "type": "string",
                        "pattern": "^(0|[1-9][0-9]{0,77})$"
                      }
                    }
                  }
                }
              }
            },
            "amount": {
              "$ref": "#/components/schemas/FiatMoney",
              "type": "object",
              "additionalProperties": false,
              "required": [
                "currency",
                "minorUnits"
              ],
              "properties": {
                "currency": {
                  "type": "string",
                  "const": "USD"
                },
                "minorUnits": {
                  "type": "string",
                  "pattern": "^(0|[1-9][0-9]{0,77})$"
                }
              }
            },
            "governingLaw": {
              "type": "string"
            },
            "rules": {
              "type": "object",
              "required": [
                "version",
                "hash"
              ],
              "properties": {
                "version": {
                  "type": "string"
                },
                "hash": {
                  "type": "string"
                }
              }
            },
            "procedure": {
              "type": "object",
              "required": [
                "name",
                "finalityPath",
                "schedule"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "const": "standard"
                },
                "finalityPath": {
                  "type": "string",
                  "const": "human_appeal"
                },
                "schedule": {
                  "type": "object",
                  "required": [
                    "profile"
                  ],
                  "properties": {
                    "profile": {
                      "type": "string",
                      "const": "standard"
                    }
                  }
                }
              }
            },
            "aiDisclosure": {
              "type": "object",
              "required": [
                "version",
                "hash"
              ],
              "properties": {
                "version": {
                  "type": "string"
                },
                "hash": {
                  "type": "string"
                }
              }
            },
            "fees": {
              "type": "object",
              "description": "Quoted filing fee in exact USD at the published schedule's precision, its collection mode, and the stated prerequisite for opening under this packet. A payable fee is completed on People's Court; this branch initiates no payment.",
              "properties": {
                "collection": {
                  "type": "string",
                  "enum": [
                    "off",
                    "waived",
                    "collect"
                  ]
                },
                "payable": {
                  "type": "boolean"
                },
                "quotedUsd": {
                  "type": "string"
                },
                "tier": {
                  "type": "string"
                },
                "prerequisite": {
                  "type": "string",
                  "enum": [
                    "none",
                    "filing_fee_paid_on_peoples_court"
                  ]
                }
              },
              "required": [
                "collection",
                "payable",
                "quotedUsd",
                "tier",
                "prerequisite"
              ]
            },
            "respondentConsent": {
              "type": "object",
              "required": [
                "mode",
                "statement"
              ],
              "properties": {
                "mode": {
                  "type": "string",
                  "const": "deferred_hosted_account"
                },
                "statement": {
                  "type": "string"
                }
              }
            },
            "requiredConfirmations": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "side",
                  "principalId",
                  "required",
                  "statement"
                ],
                "properties": {
                  "side": {
                    "type": "string",
                    "const": "claimant"
                  },
                  "principalId": {
                    "type": "string"
                  },
                  "required": {
                    "type": "boolean",
                    "const": true
                  },
                  "statement": {
                    "type": "string"
                  }
                }
              }
            },
            "declaration": {
              "type": "object",
              "required": [
                "declarantName",
                "declarantCapacity",
                "executionLocation"
              ],
              "properties": {
                "declarantName": {
                  "type": "string"
                },
                "declarantCapacity": {
                  "type": "string"
                },
                "executionLocation": {
                  "type": "string"
                }
              }
            },
            "scope": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            }
          },
          "required": [
            "schemaVersion",
            "draftId",
            "caseId",
            "draftDigest",
            "termsDigest",
            "acceptanceStatement",
            "parties",
            "claimantIdentity",
            "claimSummary",
            "claimStatement",
            "requestedItems",
            "amount",
            "governingLaw",
            "rules",
            "procedure",
            "aiDisclosure",
            "fees",
            "respondentConsent",
            "requiredConfirmations",
            "declaration",
            "scope",
            "expiresAt"
          ]
        },
        "hostedAcceptanceUrl": {
          "type": "string",
          "description": "One-use hosted acceptance link returned once at preparation. Replays and draft GET omit it. Replacement requires explicit rotateAcceptanceLink outside the connector."
        }
      },
      "required": [
        "schemaVersion",
        "filingId",
        "procedure",
        "schedule",
        "status",
        "owner",
        "draftDigest",
        "termsDigest",
        "expiresAt",
        "acceptance",
        "reviewPacket"
      ]
    },
    "requestId": {
      "type": "string"
    }
  }
}
default

RFC 9457 style problem response.

application/problem+json

{
  "$ref": "#/components/schemas/Problem",
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "code",
    "detail",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "code": {
      "type": "string"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    }
  }
}

Example response

Successful response

{
  "data": {
    "schemaVersion": "account-filing-v1",
    "filingId": "filingId_test",
    "procedure": "standard",
    "schedule": {
      "profile": "standard"
    },
    "status": "awaiting_acceptance",
    "owner": {
      "accountId": "accountId_test"
    },
    "draftDigest": "draftDigest_test",
    "termsDigest": "termsDigest_test",
    "expiresAt": "expiresAt_test",
    "acceptance": {
      "required": true,
      "method": "hosted_clickwrap",
      "recorded": false
    },
    "reviewPacket": {
      "schemaVersion": "account-filing-review-packet-v1",
      "draftId": "draft_test_123",
      "caseId": "pcase_test_123",
      "draftDigest": "draftDigest_test",
      "termsDigest": "termsDigest_test",
      "acceptanceStatement": "The test delivery did not match the agreed specification.",
      "parties": {
        "claimant": {
          "principalId": "principal_test_123",
          "name": "name_test",
          "principalKind": "individual"
        },
        "respondent": {
          "name": "name_test",
          "principalKind": "individual"
        }
      },
      "claimantIdentity": {
        "accountId": "accountId_test",
        "email": "email_test"
      },
      "claimSummary": "Test-environment contract delivery dispute.",
      "claimStatement": "The test delivery did not match the agreed specification.",
      "requestedItems": [
        {
          "id": "id_test",
          "kind": "monetary",
          "text": "Test-environment procedural message."
        }
      ],
      "amount": {
        "currency": "USD",
        "minorUnits": "12500"
      },
      "governingLaw": "governingLaw_test",
      "rules": {
        "version": "version_test",
        "hash": "hash_test"
      },
      "procedure": {
        "name": "standard",
        "finalityPath": "human_appeal",
        "schedule": {
          "profile": "standard"
        }
      },
      "aiDisclosure": {
        "version": "version_test",
        "hash": "hash_test"
      },
      "fees": {
        "collection": "off",
        "payable": false,
        "quotedUsd": "quotedUsd_test",
        "tier": "tier_test",
        "prerequisite": "none"
      },
      "respondentConsent": {
        "mode": "deferred_hosted_account",
        "statement": "The test delivery did not match the agreed specification."
      },
      "requiredConfirmations": [
        {
          "side": "claimant",
          "principalId": "principal_test_123",
          "required": true,
          "statement": "The test delivery did not match the agreed specification."
        }
      ],
      "declaration": {
        "declarantName": "declarantName_test",
        "declarantCapacity": "declarantCapacity_test",
        "executionLocation": "executionLocation_test"
      },
      "scope": "scope_test",
      "expiresAt": "expiresAt_test"
    }
  },
  "requestId": "requestId_test"
}

Errors

Read the response status and stable error code. See errors and rate limits for recovery. Refresh the resource before resolving a state or digest conflict.

Idempotency and retries

  • For throttling, honor Retry-After when present. Back off on retryable server failures.
  • Send a unique Idempotency-Key. An exact retry returns the stored result; reusing the key with a different request fails.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.