Economicoingestions.resolve
Revise a completed expense proposal using existing targets and its expected revision. Original evidence is preserved; no bill, payment or automatic delivery is created.
What it does
Resolve a completed expense proposal by selecting existing targets against expectedProposalRevision (initial revision 1). For observed invoices supply exact retained extraction text as invoiceText; optionally correct its canonical source choices using invoiceChoices from ingestions.invoice_candidates. Caller choices carry separate provenance, not model probabilities, and re-run complete source/money checks. Original source, extraction, classification and model choices remain unchanged; bounded previous proposal/correction snapshots remain visible. Maximum 8 revisions / 256 KiB history.
Requires full source/business/contract/party/ledger/report reads. Pending or recorded automatic jobs cannot be revised; refused jobs remain manual. Receipt-classified ingestions are refused: review them with ingestions.receipt_proposal. Creates no bill, payment or automatic delivery; ready proposals use ordinary commands separately. Unobserved fact assertions and original verification are unsupported.
Before you send it
An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe ingestions.resolve through GET /v1/catalog/commands/{name} before acting.
This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.
Inputs
Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
ingestionId | string | Yes | Example: "ing_example". |
expectedProposalRevision | integer | Yes | Minimum: 1. Maximum: 7. Example: 1. |
expenseTargets | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. Example: "ctr_existing". |
expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. Example: "expense". |
invoiceText | string | No | Maximum length: 65536. |
invoiceChoices | object | No | |
invoiceChoices.headers | object | Yes | |
invoiceChoices.headers.vendor | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceChoices.headers.buyer | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceChoices.headers.externalId | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceChoices.headers.date | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceChoices.headers.currency | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceChoices.headers.total | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceChoices.service | string | Yes | Choose "delivered", "not_delivered", "unclear". |
invoiceChoices.rows | array | Yes | Items: object. Maximum items: 64. |
invoiceChoices.rows[].role | string | Yes | Choose "charge", "tax", "summary", "other", "unclear". |
invoiceChoices.rows[].amount | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
After acceptance
When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.
Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.
Result fields
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
ingestionId | string | Yes | |
createdAt | string | Yes | Format: date-time. |
status | string | Yes | Choose "awaiting_upload", "queued", "processing", "completed", "failed". |
source | object | No | |
source.documentId | string | Yes | |
source.cid | string | Yes | |
source.format | string | Yes | Choose "markdown", "text", "document". |
source.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
expenseTargets | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
mode | string | No | Choose "propose", "auto_record". |
recordingPolicy | object | No | |
recordingPolicy.minimumConfidencePercent | integer | Yes | Minimum: 60. Maximum: 100. |
recordingPolicy.fundingAccounts | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
recordingPolicy.fundingAccounts[].financialAccountId | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.fundingAccounts[].currency | string | Yes | Pattern: "^[A-Z]{3}$". |
recordingPolicy.fundingAccounts[].last4 | string | Yes | Pattern: "^[0-9]{4}$". |
recordingPolicy.fundingAccounts[].kind | string | Yes | Choose "checking", "savings", "card", "wallet", "other". |
recordingPolicy.fundingAccounts[].glAccountCode | number | Yes | Choose 1110, 1310, 1410, 2190, 2135. |
recordingPolicy.fundingAccounts[].ownerPartyId | string | No | Minimum length: 1. |
recordingPolicy.fundingAccounts[].providerPartyId | string | No | Minimum length: 1. |
recordingPolicy.targets | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
recordingPolicy.targets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.targets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.targets[].cid | string | Yes | Minimum length: 1. Maximum length: 128. |
execution | object | No | Durable financial recording disposition and actual ordinary command receipt reference. |
execution.status | string | Yes | Choose "pending", "recorded", "already_recorded", "needs_review". |
execution.proposalRevision | integer | Yes | Minimum: 1. Maximum: 8. |
execution.commandId | string | No | Actual ordinary financial command receipt. |
execution.occurrenceId | string | No | An already recorded matching economic fact. |
execution.reason | string | No | Why automatic recording requires review. |
proposal | object | No | Frozen source-backed expense proposal. Proposal generation creates no financial entries. Choose a matching alternative in the exact schema below. |
proposal.disposition | string | Yes | Choose "ready", "needs_information", "duplicate", "unsupported". |
proposal.source | object | Yes | |
proposal.source.documentId | string | Yes | Minimum length: 1. |
proposal.source.cid | string | Yes | Minimum length: 1. |
proposal.missing | array | Yes | Items: string. Maximum items: 100. |
proposal.lines | array | Yes | Items: object. Maximum items: 500. |
proposal.lines[].index | integer | Yes | Minimum: 0. |
proposal.lines[].description | string | Yes | Minimum length: 1. |
proposal.lines[].amountMinor | string | Yes | Pattern: "^[0-9]+$". |
proposal.currency | string | No | Pattern: "^[A-Z]{3}$". |
proposal.totalMinor | string | No | Pattern: "^[0-9]+$". |
proposal.matchedOccurrenceId | string | No | An existing matching economic fact. Minimum length: 1. |
proposal.contract | object | No | |
proposal.contract.contractId | string | Yes | Minimum length: 1. |
proposal.contract.documentId | string | Yes | Minimum length: 1. |
proposal.contract.cid | string | Yes | Minimum length: 1. |
proposal.command | schema-defined | No | Choose a matching alternative in the exact schema below. |
proposal.interpretation | object | No | |
proposal.interpretation.cid | string | Yes | Minimum length: 1. |
proposal.interpretation.promptVersion | string | Yes | Minimum length: 1. |
proposal.interpretation.buyer | string | No | Exact observed buyer; historical proposals without this field remain review cases. Minimum length: 1. |
proposal.interpretation.spans | array | Yes | Items: object. Maximum items: 1000. |
proposal.interpretation.spans[].start | integer | Yes | Minimum: 0. |
proposal.interpretation.spans[].end | integer | Yes | Minimum: 1. Maximum: 65536. |
proposal.interpretation.spans[].text | string | Yes | Minimum length: 1. |
proposal.preview | schema-defined | No | Read-only ordinary activity or priced-rights preparation, when validation succeeds. |
invoiceCorrection | object | No | |
invoiceCorrection.at | string | Yes | Format: date-time. |
invoiceCorrection.principal | string | Yes | |
invoiceCorrection.provenance | string | Yes | Must be "caller_selected_source_spans". |
invoiceCorrection.choices | object | Yes | |
invoiceCorrection.choices.headers | object | Yes | |
invoiceCorrection.choices.headers.vendor | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.buyer | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.externalId | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.date | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.currency | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.total | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.service | string | Yes | Choose "delivered", "not_delivered", "unclear". |
invoiceCorrection.choices.rows | array | Yes | Items: object. Maximum items: 64. |
invoiceCorrection.choices.rows[].role | string | Yes | Choose "charge", "tax", "summary", "other", "unclear". |
invoiceCorrection.choices.rows[].amount | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalRevision | integer | No | Minimum: 2. Maximum: 8. |
proposalHistory | array | No | Items: object. Maximum items: 7. |
proposalHistory[].revision | integer | Yes | Minimum: 1. Maximum: 7. |
proposalHistory[].at | string | Yes | Format: date-time. |
proposalHistory[].principal | string | Yes | |
proposalHistory[].expenseTargets | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
proposalHistory[].expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
proposalHistory[].expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
proposalHistory[].proposal | object | No | Frozen source-backed expense proposal. Proposal generation creates no financial entries. Choose a matching alternative in the exact schema below. |
proposalHistory[].proposal.disposition | string | Yes | Choose "ready", "needs_information", "duplicate", "unsupported". |
proposalHistory[].proposal.source | object | Yes | |
proposalHistory[].proposal.source.documentId | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.source.cid | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.missing | array | Yes | Items: string. Maximum items: 100. |
proposalHistory[].proposal.lines | array | Yes | Items: object. Maximum items: 500. |
proposalHistory[].proposal.lines[].index | integer | Yes | Minimum: 0. |
proposalHistory[].proposal.lines[].description | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.lines[].amountMinor | string | Yes | Pattern: "^[0-9]+$". |
proposalHistory[].proposal.currency | string | No | Pattern: "^[A-Z]{3}$". |
proposalHistory[].proposal.totalMinor | string | No | Pattern: "^[0-9]+$". |
proposalHistory[].proposal.matchedOccurrenceId | string | No | An existing matching economic fact. Minimum length: 1. |
proposalHistory[].proposal.contract | object | No | |
proposalHistory[].proposal.contract.contractId | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.contract.documentId | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.contract.cid | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.command | schema-defined | No | Choose a matching alternative in the exact schema below. |
proposalHistory[].proposal.interpretation | object | No | |
proposalHistory[].proposal.interpretation.cid | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.interpretation.promptVersion | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.interpretation.buyer | string | No | Exact observed buyer; historical proposals without this field remain review cases. Minimum length: 1. |
proposalHistory[].proposal.interpretation.spans | array | Yes | Items: object. Maximum items: 1000. |
proposalHistory[].proposal.interpretation.spans[].start | integer | Yes | Minimum: 0. |
proposalHistory[].proposal.interpretation.spans[].end | integer | Yes | Minimum: 1. Maximum: 65536. |
proposalHistory[].proposal.interpretation.spans[].text | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.preview | schema-defined | No | Read-only ordinary activity or priced-rights preparation, when validation succeeds. |
proposalHistory[].invoiceCorrection | object | No | |
proposalHistory[].invoiceCorrection.at | string | Yes | Format: date-time. |
proposalHistory[].invoiceCorrection.principal | string | Yes | |
proposalHistory[].invoiceCorrection.provenance | string | Yes | Must be "caller_selected_source_spans". |
proposalHistory[].invoiceCorrection.choices | object | Yes | |
proposalHistory[].invoiceCorrection.choices.headers | object | Yes | |
proposalHistory[].invoiceCorrection.choices.headers.vendor | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.buyer | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.externalId | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.date | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.currency | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.total | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.service | string | Yes | Choose "delivered", "not_delivered", "unclear". |
proposalHistory[].invoiceCorrection.choices.rows | array | Yes | Items: object. Maximum items: 64. |
proposalHistory[].invoiceCorrection.choices.rows[].role | string | Yes | Choose "charge", "tax", "summary", "other", "unclear". |
proposalHistory[].invoiceCorrection.choices.rows[].amount | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
original | object | No | |
original.documentId | string | Yes | |
original.cid | string | Yes | |
original.format | string | Yes | Choose "markdown", "text", "document". |
original.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
failure | object | No | |
failure.reason | string | Yes | |
failure.retryable | boolean | Yes | |
lastFailure | object | No | |
lastFailure.reason | string | Yes | |
lastFailure.retryable | boolean | Yes | |
lastFailure.attempt | integer | Yes | Minimum: 1. Maximum: 12. |
lastFailure.at | string | Yes | Format: date-time. |
relationship | object | No | |
relationship.type | string | Yes | Choose "transcription", "summary", "related_original". |
relationship.declaredBy | string | Yes | |
relationship.verification | string | Yes | Must be "unverified". |
uploads | object | Yes | |
uploads.primary | object | No | |
uploads.primary.filename | string | Yes | Minimum length: 1. Maximum length: 200. |
uploads.primary.contentType | string | Yes | Choose "application/pdf", "text/plain", "text/markdown", "text/csv", "application/json", "image/png", "image/jpeg", "image/webp". |
uploads.primary.size | integer | Yes | Exact byte length. Images are limited to 256 KiB; other files to 10 MiB. Minimum: 1. Maximum: 10485760. |
uploads.primary.expiresAt | string | Yes | Format: date-time. |
uploads.primary.status | string | Yes | Choose "awaiting_upload", "uploaded", "expired". |
uploads.primary.documentId | string | No | |
uploads.primary.cid | string | No | |
uploads.primary.url | string | No | Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one. |
uploads.primary.method | string | No | Present when this response issued the upload URL. Must be "PUT". |
uploads.original | object | No | |
uploads.original.filename | string | Yes | Minimum length: 1. Maximum length: 200. |
uploads.original.contentType | string | Yes | Choose "application/pdf", "text/plain", "text/markdown", "text/csv", "application/json", "image/png", "image/jpeg", "image/webp". |
uploads.original.size | integer | Yes | Exact byte length. Images are limited to 256 KiB; other files to 10 MiB. Minimum: 1. Maximum: 10485760. |
uploads.original.expiresAt | string | Yes | Format: date-time. |
uploads.original.status | string | Yes | Choose "awaiting_upload", "uploaded", "expired". |
uploads.original.documentId | string | No | |
uploads.original.cid | string | No | |
uploads.original.url | string | No | Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one. |
uploads.original.method | string | No | Present when this response issued the upload URL. Must be "PUT". |
revisions | array | Yes | Items: object. |
revisions[].revision | integer | Yes | Minimum: 1. |
revisions[].startedAt | string | Yes | Format: date-time. |
revisions[].business | object | Yes | |
revisions[].business.name | string | Yes | |
revisions[].business.legalName | string or null | Yes | |
revisions[].completedAt | string | No | Format: date-time. |
revisions[].status | string | Yes | Choose "processing", "completed", "failed". |
revisions[].sources | array | Yes | Items: object. |
revisions[].sources[].documentId | string | Yes | |
revisions[].sources[].cid | string | Yes | |
revisions[].sources[].format | string | Yes | Choose "markdown", "text", "document". |
revisions[].sources[].provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
revisions[].sources[].role | string | Yes | Choose "primary", "original". |
revisions[].failure | object | No | |
revisions[].failure.reason | string | Yes | |
revisions[].failure.retryable | boolean | Yes | |
revisions[].invoiceSelection | object | No | Observed source-span choices, bound to the committed UTF-8 extraction. Spans versions pick candidate indices; fields versions carry verified UTF-8 spans for header and payment-identity values. Choice probability is not financial accuracy or authorization. |
revisions[].invoiceSelection.textCid | string | Yes | |
revisions[].invoiceSelection.promptVersion | string | Yes | Choose "invoice-fields-v5", "receipt-fields-v5", "invoice-spans-v1", "receipt-spans-v1", "invoice-fields-v1", "receipt-fields-v1", "invoice-fields-v2", "receipt-fields-v2", "invoice-fields-v3", "receipt-fields-v3", "invoice-fields-v4", "receipt-fields-v4". |
revisions[].invoiceSelection.headers | object | Yes | |
revisions[].invoiceSelection.headers.vendor | object | Yes | |
revisions[].invoiceSelection.headers.vendor.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.vendor.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.vendor.span | object | No | |
revisions[].invoiceSelection.headers.vendor.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.vendor.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.vendor.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.buyer | object | Yes | |
revisions[].invoiceSelection.headers.buyer.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.buyer.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.buyer.span | object | No | |
revisions[].invoiceSelection.headers.buyer.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.buyer.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.buyer.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.externalId | object | Yes | |
revisions[].invoiceSelection.headers.externalId.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.externalId.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.externalId.span | object | No | |
revisions[].invoiceSelection.headers.externalId.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.externalId.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.externalId.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.date | object | Yes | |
revisions[].invoiceSelection.headers.date.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.date.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.date.span | object | No | |
revisions[].invoiceSelection.headers.date.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.date.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.date.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.currency | object | Yes | |
revisions[].invoiceSelection.headers.currency.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.currency.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.currency.span | object | No | |
revisions[].invoiceSelection.headers.currency.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.currency.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.currency.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.total | object | Yes | |
revisions[].invoiceSelection.headers.total.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.total.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.total.span | object | No | |
revisions[].invoiceSelection.headers.total.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.total.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.total.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.provider | object | No | The model that chose header values and optional source-line amounts: Clef for spans versions, Clairic for fields versions. |
revisions[].invoiceSelection.provider.name | string | Yes | Choose "@cf/cloudflare/clef-flash", "@cf/cloudflare/clef", "@cf/cloudflare/clairic". |
revisions[].invoiceSelection.provider.version | string | Yes | Must be "unreported". |
revisions[].invoiceSelection.provider.inputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.provider.outputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.provider.requestBytes | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.provider.latencyMs | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider | object | No | Fields versions only: the Clef model or bounded Flash-to-Clef cascade that answered currency, service, payment status and row judgments. Optional Clairic amount reads are accounted in provider. |
revisions[].invoiceSelection.judgmentProvider.name | string | Yes | Choose "@cf/cloudflare/clef-flash", "@cf/cloudflare/clef", "@cf/cloudflare/clef-flash+clef/uncertain-groups-v1". |
revisions[].invoiceSelection.judgmentProvider.version | string | Yes | Must be "unreported". |
revisions[].invoiceSelection.judgmentProvider.inputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider.outputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider.requestBytes | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider.latencyMs | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider | object | No | Measured optional grouping attempt, including a failed attempt that retains physical rows. |
revisions[].invoiceSelection.groupingProvider.name | string | Yes | Choose "@cf/moonshotai/kimi-k2.6". |
revisions[].invoiceSelection.groupingProvider.version | string | Yes | Must be "unreported". |
revisions[].invoiceSelection.groupingProvider.inputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider.outputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider.requestBytes | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider.latencyMs | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.rowGroups | array | No | Items: object. Maximum items: 1024. |
revisions[].invoiceSelection.rowGroups[].firstRow | integer | Yes | Minimum: 0. Maximum: 1023. |
revisions[].invoiceSelection.rowGroups[].lastRow | integer | Yes | Minimum: 0. Maximum: 1023. |
revisions[].invoiceSelection.rowGroups[].anchorRow | integer | Yes | Minimum: 0. Maximum: 1023. |
revisions[].invoiceSelection.rowGroups[].description | object | No | |
revisions[].invoiceSelection.rowGroups[].description.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rowGroups[].description.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rowGroups[].description.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.service | object | Yes | |
revisions[].invoiceSelection.service.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.service.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.service.span | object | No | |
revisions[].invoiceSelection.service.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.service.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.service.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.payment | object | No | |
revisions[].invoiceSelection.payment.status | object | Yes | |
revisions[].invoiceSelection.payment.status.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.payment.status.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.payment.status.span | object | No | |
revisions[].invoiceSelection.payment.status.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.status.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.status.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.payment.externalId | object | Yes | |
revisions[].invoiceSelection.payment.externalId.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.payment.externalId.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.payment.externalId.span | object | No | |
revisions[].invoiceSelection.payment.externalId.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.externalId.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.externalId.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.payment.last4 | object | Yes | |
revisions[].invoiceSelection.payment.last4.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.payment.last4.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.payment.last4.span | object | No | |
revisions[].invoiceSelection.payment.last4.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.last4.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.last4.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.rows | array | Yes | Items: object. Maximum items: 1024. |
revisions[].invoiceSelection.rows[].role | object | Yes | |
revisions[].invoiceSelection.rows[].role.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.rows[].role.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.rows[].role.span | object | No | |
revisions[].invoiceSelection.rows[].role.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].role.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].role.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.rows[].amount | object | Yes | |
revisions[].invoiceSelection.rows[].amount.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.rows[].amount.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.rows[].amount.span | object | No | |
revisions[].invoiceSelection.rows[].amount.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].amount.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].amount.span.text | string | Yes | Maximum length: 65536. |
revisions[].extraction | object | No | |
revisions[].extraction.status | string | Yes | Choose "not_required", "extracted", "incomplete". |
revisions[].extraction.method | string | Yes | Choose "provided_text", "native_pdf", "image_ocr", "pdf_ocr". |
revisions[].extraction.text | string | No | Returned only after source-document authorization; raw history contains annex references. Maximum length: 65536. |
revisions[].extraction.textBytes | integer | Yes | Minimum: 1. Maximum: 65536. |
revisions[].extraction.source | object | Yes | |
revisions[].extraction.source.documentId | string | Yes | |
revisions[].extraction.source.cid | string | Yes | |
revisions[].extraction.source.format | string | Yes | Choose "markdown", "text", "document". |
revisions[].extraction.source.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
revisions[].extraction.derived | object | Yes | |
revisions[].extraction.derived.cid | string | Yes | |
revisions[].extraction.pageCount | integer or null | Yes | Minimum: 1. Maximum: 50. |
revisions[].extraction.locations | array | Yes | Items: object. Maximum items: 50. |
revisions[].extraction.locations[].page | integer or null | Yes | Minimum: 1. |
revisions[].extraction.locations[].start | integer | Yes | Minimum: 0. |
revisions[].extraction.locations[].end | integer | Yes | Minimum: 0. |
revisions[].extraction.provider | object | Yes | |
revisions[].extraction.provider.name | string | Yes | |
revisions[].extraction.provider.version | string | Yes | |
revisions[].extraction.usage | object | Yes | |
revisions[].extraction.usage.inputTokens | integer | Yes | Minimum: 0. |
revisions[].extraction.usage.outputTokens | integer | Yes | Minimum: 0. |
revisions[].extraction.usage.latencyMs | integer | Yes | Minimum: 0. |
revisions[].extraction.usage.conversionTokens | integer | No | Estimated native conversion tokens, distinct from inference usage. Minimum: 0. |
revisions[].classification | object | No | |
revisions[].classification.documentType | string | Yes | Choose "invoice", "receipt", "agreement", "statement_or_remittance", "credit_or_correction", "reminder", "mixed", "other", "uncertain". |
revisions[].classification.probabilities | object | Yes | |
revisions[].classification.probabilities.invoice | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.receipt | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.agreement | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.statement_or_remittance | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.credit_or_correction | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.reminder | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.mixed | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.other | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.uncertain | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.model | string | Yes | |
revisions[].classification.modelVersion | string | Yes | |
revisions[].classification.promptVersion | string | Yes | |
revisions[].classification.confidence | string | No | Distribution confidence, not calibrated accuracy or permission to act. |
revisions[].classification.invoiceRole | object | No | |
revisions[].classification.invoiceRole.role | string | Yes | Choose "buyer", "seller", "neither", "unclear". |
revisions[].classification.invoiceRole.probabilities | object | Yes | |
revisions[].classification.invoiceRole.probabilities.buyer | string | Yes | |
revisions[].classification.invoiceRole.probabilities.seller | string | Yes | |
revisions[].classification.invoiceRole.probabilities.neither | string | Yes | |
revisions[].classification.invoiceRole.probabilities.unclear | string | Yes | |
revisions[].classification.invoiceRole.confidence | string | Yes | |
revisions[].classification.invoiceRole.promptVersion | string | Yes | |
revisions[].classification.usage | object | No | |
revisions[].classification.usage.inputTokens | integer | Yes | Minimum: 0. |
revisions[].classification.usage.outputTokens | integer | Yes | Minimum: 0. |
revisions[].classification.usage.requestBytes | integer | Yes | Minimum: 1. |
revisions[].classification.usage.latencyMs | integer | Yes | Minimum: 0. |
All commands · Operation and errors · Reusable schemas
Keep credentials out of prompts; rehearse writes only in a disposable sandbox.
Exact request schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"const": "ingestions.resolve"
},
"input": {
"type": "object",
"additionalProperties": false,
"properties": {
"ingestionId": {
"type": "string"
},
"expectedProposalRevision": {
"type": "integer",
"minimum": 1,
"maximum": 7
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
}
},
"invoiceText": {
"type": "string",
"maxLength": 65536
},
"invoiceChoices": {
"type": "object",
"additionalProperties": false,
"properties": {
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"buyer": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"externalId": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"date": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"currency": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"total": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"service": {
"enum": [
"delivered",
"not_delivered",
"unclear"
]
},
"rows": {
"type": "array",
"maxItems": 64,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"charge",
"tax",
"summary",
"other",
"unclear"
]
},
"amount": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"headers",
"service",
"rows"
]
}
},
"required": [
"ingestionId",
"expectedProposalRevision",
"expenseTargets"
]
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"effective_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"name",
"input",
"idempotency_key",
"effective_at"
],
"additionalProperties": false
}Accepted command receipt
{
"type": "object",
"required": [
"commandId",
"replayed",
"result",
"events"
],
"properties": {
"commandId": {
"type": "string"
},
"replayed": {
"type": "boolean"
},
"imported": {
"const": true,
"description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
},
"result": {
"type": "object",
"additionalProperties": false,
"properties": {
"ingestionId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"awaiting_upload",
"queued",
"processing",
"completed",
"failed"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance"
]
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
}
},
"mode": {
"enum": [
"propose",
"auto_record"
]
},
"recordingPolicy": {
"type": "object",
"additionalProperties": false,
"properties": {
"minimumConfidencePercent": {
"type": "integer",
"minimum": 60,
"maximum": 100
},
"fundingAccounts": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"currency",
"last4",
"kind",
"glAccountCode"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"last4": {
"type": "string",
"pattern": "^[0-9]{4}$"
},
"kind": {
"enum": [
"checking",
"savings",
"card",
"wallet",
"other"
]
},
"glAccountCode": {
"enum": [
1110,
1310,
1410,
2190,
2135
]
},
"ownerPartyId": {
"type": "string",
"minLength": 1
},
"providerPartyId": {
"type": "string",
"minLength": 1
}
}
}
},
"targets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"cid": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey",
"cid"
]
}
}
},
"required": [
"minimumConfidencePercent",
"targets"
]
},
"execution": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"enum": [
"pending",
"recorded",
"already_recorded",
"needs_review"
]
},
"proposalRevision": {
"type": "integer",
"minimum": 1,
"maximum": 8
},
"commandId": {
"type": "string",
"description": "Actual ordinary financial command receipt."
},
"occurrenceId": {
"type": "string",
"description": "An already recorded matching economic fact."
},
"reason": {
"type": "string",
"description": "Why automatic recording requires review."
}
},
"required": [
"status",
"proposalRevision"
],
"description": "Durable financial recording disposition and actual ordinary command receipt reference."
},
"proposal": {
"type": "object",
"additionalProperties": false,
"description": "Frozen source-backed expense proposal. Proposal generation creates no financial entries.",
"required": [
"disposition",
"source",
"missing",
"lines"
],
"properties": {
"disposition": {
"enum": [
"ready",
"needs_information",
"duplicate",
"unsupported"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentId",
"cid"
]
},
"missing": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 500
}
},
"lines": {
"type": "array",
"maxItems": 500,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"description": {
"type": "string",
"minLength": 1
},
"amountMinor": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"required": [
"index",
"description",
"amountMinor"
]
}
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"totalMinor": {
"type": "string",
"pattern": "^[0-9]+$"
},
"matchedOccurrenceId": {
"type": "string",
"minLength": 1,
"description": "An existing matching economic fact."
},
"contract": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"contractId",
"documentId",
"cid"
]
},
"command": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "contracts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"facts",
"evidence"
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"phase": {
"const": "billing"
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"type": "string"
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"service"
],
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
}
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "receipts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"billing",
"payment"
],
"properties": {
"processing": {
"type": "object",
"additionalProperties": false,
"required": [
"rail",
"netAmount",
"evidence"
],
"properties": {
"rail": {
"enum": [
"ach",
"ach_same_day",
"fedwire",
"rtp",
"sepa",
"sepa_instant",
"swift",
"onchain",
"internal",
"card"
]
},
"netAmount": {
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$"
},
"feeFacts": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
}
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"billing": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"phase"
],
"anyOf": [
{
"type": "object",
"properties": {
"obligationKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"obligationKey"
]
},
{
"type": "object",
"properties": {
"period": {
"type": "object",
"properties": {
"from": {
"type": "string",
"minLength": 1
},
"through": {
"type": "string",
"minLength": 1
}
},
"required": [
"from",
"through"
]
}
},
"required": [
"period"
]
}
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"phase": {
"const": "billing"
},
"dueDate": {
"type": "string",
"format": "date"
},
"exchangeRate": {
"type": "object",
"additionalProperties": false,
"required": [
"base",
"quote",
"date",
"numerator",
"denominator",
"evidence"
],
"description": "An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store.",
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"date": {
"type": "string",
"format": "date"
},
"numerator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"denominator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string"
}
}
}
}
}
},
"period": {
"type": "object",
"additionalProperties": false,
"required": [
"from",
"through"
],
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"through": {
"type": "string",
"format": "date-time"
}
}
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"occurrenceId"
],
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"claimId",
"component"
],
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"component": {
"type": "object",
"additionalProperties": false,
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
}
}
]
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"acceptance": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"economic": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
},
"payment": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"direction",
"amount",
"currency",
"partyId",
"effectiveAt",
"sourceFactId",
"evidence"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1
},
"direction": {
"enum": [
"in",
"out"
]
},
"amount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"currency": {
"type": "string",
"minLength": 1
},
"partyId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
}
}
}
]
},
"interpretation": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string",
"minLength": 1
},
"promptVersion": {
"type": "string",
"minLength": 1
},
"buyer": {
"type": "string",
"minLength": 1,
"description": "Exact observed buyer; historical proposals without this field remain review cases."
},
"spans": {
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"text"
]
}
}
},
"required": [
"cid",
"promptVersion",
"spans"
]
},
"preview": {
"description": "Read-only ordinary activity or priced-rights preparation, when validation succeeds."
}
},
"oneOf": [
{
"properties": {
"disposition": {
"const": "ready"
},
"missing": {
"maxItems": 0
},
"lines": {
"minItems": 1
}
},
"required": [
"command",
"contract",
"currency",
"totalMinor"
]
},
{
"properties": {
"disposition": {
"enum": [
"needs_information",
"duplicate",
"unsupported"
]
}
},
"not": {
"required": [
"command"
]
}
}
]
},
"invoiceCorrection": {
"type": "object",
"additionalProperties": false,
"properties": {
"at": {
"type": "string",
"format": "date-time"
},
"principal": {
"type": "string"
},
"provenance": {
"const": "caller_selected_source_spans"
},
"choices": {
"type": "object",
"additionalProperties": false,
"properties": {
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"buyer": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"externalId": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"date": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"currency": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"total": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"service": {
"enum": [
"delivered",
"not_delivered",
"unclear"
]
},
"rows": {
"type": "array",
"maxItems": 64,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"charge",
"tax",
"summary",
"other",
"unclear"
]
},
"amount": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"headers",
"service",
"rows"
]
}
},
"required": [
"at",
"principal",
"provenance",
"choices"
]
},
"proposalRevision": {
"type": "integer",
"minimum": 2,
"maximum": 8
},
"proposalHistory": {
"type": "array",
"maxItems": 7,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"revision": {
"type": "integer",
"minimum": 1,
"maximum": 7
},
"at": {
"type": "string",
"format": "date-time"
},
"principal": {
"type": "string"
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
}
},
"proposal": {
"type": "object",
"additionalProperties": false,
"description": "Frozen source-backed expense proposal. Proposal generation creates no financial entries.",
"required": [
"disposition",
"source",
"missing",
"lines"
],
"properties": {
"disposition": {
"enum": [
"ready",
"needs_information",
"duplicate",
"unsupported"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentId",
"cid"
]
},
"missing": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 500
}
},
"lines": {
"type": "array",
"maxItems": 500,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"description": {
"type": "string",
"minLength": 1
},
"amountMinor": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"required": [
"index",
"description",
"amountMinor"
]
}
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"totalMinor": {
"type": "string",
"pattern": "^[0-9]+$"
},
"matchedOccurrenceId": {
"type": "string",
"minLength": 1,
"description": "An existing matching economic fact."
},
"contract": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"contractId",
"documentId",
"cid"
]
},
"command": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "contracts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"facts",
"evidence"
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"phase": {
"const": "billing"
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"type": "string"
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"service"
],
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
}
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "receipts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"billing",
"payment"
],
"properties": {
"processing": {
"type": "object",
"additionalProperties": false,
"required": [
"rail",
"netAmount",
"evidence"
],
"properties": {
"rail": {
"enum": [
"ach",
"ach_same_day",
"fedwire",
"rtp",
"sepa",
"sepa_instant",
"swift",
"onchain",
"internal",
"card"
]
},
"netAmount": {
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$"
},
"feeFacts": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
}
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"billing": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"phase"
],
"anyOf": [
{
"type": "object",
"properties": {
"obligationKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"obligationKey"
]
},
{
"type": "object",
"properties": {
"period": {
"type": "object",
"properties": {
"from": {
"type": "string",
"minLength": 1
},
"through": {
"type": "string",
"minLength": 1
}
},
"required": [
"from",
"through"
]
}
},
"required": [
"period"
]
}
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"phase": {
"const": "billing"
},
"dueDate": {
"type": "string",
"format": "date"
},
"exchangeRate": {
"type": "object",
"additionalProperties": false,
"required": [
"base",
"quote",
"date",
"numerator",
"denominator",
"evidence"
],
"description": "An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store.",
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"date": {
"type": "string",
"format": "date"
},
"numerator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"denominator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string"
}
}
}
}
}
},
"period": {
"type": "object",
"additionalProperties": false,
"required": [
"from",
"through"
],
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"through": {
"type": "string",
"format": "date-time"
}
}
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"occurrenceId"
],
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"claimId",
"component"
],
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"component": {
"type": "object",
"additionalProperties": false,
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
}
}
]
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"acceptance": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"economic": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
},
"payment": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"direction",
"amount",
"currency",
"partyId",
"effectiveAt",
"sourceFactId",
"evidence"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1
},
"direction": {
"enum": [
"in",
"out"
]
},
"amount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"currency": {
"type": "string",
"minLength": 1
},
"partyId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
}
}
}
]
},
"interpretation": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string",
"minLength": 1
},
"promptVersion": {
"type": "string",
"minLength": 1
},
"buyer": {
"type": "string",
"minLength": 1,
"description": "Exact observed buyer; historical proposals without this field remain review cases."
},
"spans": {
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"text"
]
}
}
},
"required": [
"cid",
"promptVersion",
"spans"
]
},
"preview": {
"description": "Read-only ordinary activity or priced-rights preparation, when validation succeeds."
}
},
"oneOf": [
{
"properties": {
"disposition": {
"const": "ready"
},
"missing": {
"maxItems": 0
},
"lines": {
"minItems": 1
}
},
"required": [
"command",
"contract",
"currency",
"totalMinor"
]
},
{
"properties": {
"disposition": {
"enum": [
"needs_information",
"duplicate",
"unsupported"
]
}
},
"not": {
"required": [
"command"
]
}
}
]
},
"invoiceCorrection": {
"type": "object",
"additionalProperties": false,
"properties": {
"at": {
"type": "string",
"format": "date-time"
},
"principal": {
"type": "string"
},
"provenance": {
"const": "caller_selected_source_spans"
},
"choices": {
"type": "object",
"additionalProperties": false,
"properties": {
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"buyer": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"externalId": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"date": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"currency": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"total": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"service": {
"enum": [
"delivered",
"not_delivered",
"unclear"
]
},
"rows": {
"type": "array",
"maxItems": 64,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"charge",
"tax",
"summary",
"other",
"unclear"
]
},
"amount": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"headers",
"service",
"rows"
]
}
},
"required": [
"at",
"principal",
"provenance",
"choices"
]
}
},
"required": [
"revision",
"at",
"principal"
]
}
},
"original": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance"
]
},
"failure": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"reason",
"retryable"
]
},
"lastFailure": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"attempt": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"reason",
"retryable",
"attempt",
"at"
]
},
"relationship": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"transcription",
"summary",
"related_original"
]
},
"declaredBy": {
"type": "string"
},
"verification": {
"const": "unverified"
}
},
"required": [
"type",
"declaredBy",
"verification"
]
},
"uploads": {
"type": "object",
"additionalProperties": false,
"properties": {
"primary": {
"type": "object",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contentType": {
"enum": [
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
"image/png",
"image/jpeg",
"image/webp"
]
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 10485760,
"description": "Exact byte length. Images are limited to 256 KiB; other files to 10 MiB."
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"awaiting_upload",
"uploaded",
"expired"
]
},
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"url": {
"type": "string",
"description": "Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one."
},
"method": {
"const": "PUT",
"description": "Present when this response issued the upload URL."
}
},
"required": [
"filename",
"contentType",
"size",
"expiresAt",
"status"
]
},
"original": {
"type": "object",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contentType": {
"enum": [
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
"image/png",
"image/jpeg",
"image/webp"
]
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 10485760,
"description": "Exact byte length. Images are limited to 256 KiB; other files to 10 MiB."
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"awaiting_upload",
"uploaded",
"expired"
]
},
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"url": {
"type": "string",
"description": "Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one."
},
"method": {
"const": "PUT",
"description": "Present when this response issued the upload URL."
}
},
"required": [
"filename",
"contentType",
"size",
"expiresAt",
"status"
]
}
}
},
"revisions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"revision": {
"type": "integer",
"minimum": 1
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"business": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"legalName": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"legalName"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"processing",
"completed",
"failed"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
},
"role": {
"enum": [
"primary",
"original"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance",
"role"
]
}
},
"failure": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"reason",
"retryable"
]
},
"invoiceSelection": {
"type": "object",
"additionalProperties": false,
"description": "Observed source-span choices, bound to the committed UTF-8 extraction. Spans versions pick candidate indices; fields versions carry verified UTF-8 spans for header and payment-identity values. Choice probability is not financial accuracy or authorization.",
"properties": {
"textCid": {
"type": "string"
},
"promptVersion": {
"enum": [
"invoice-fields-v5",
"receipt-fields-v5",
"invoice-spans-v1",
"receipt-spans-v1",
"invoice-fields-v1",
"receipt-fields-v1",
"invoice-fields-v2",
"receipt-fields-v2",
"invoice-fields-v3",
"receipt-fields-v3",
"invoice-fields-v4",
"receipt-fields-v4"
]
},
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"buyer": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"externalId": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"date": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"currency": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"total": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"provider": {
"type": "object",
"additionalProperties": false,
"description": "The model that chose header values and optional source-line amounts: Clef for spans versions, Clairic for fields versions.",
"properties": {
"name": {
"enum": [
"@cf/cloudflare/clef-flash",
"@cf/cloudflare/clef",
"@cf/cloudflare/clairic"
]
},
"version": {
"const": "unreported"
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"version",
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
},
"judgmentProvider": {
"type": "object",
"additionalProperties": false,
"description": "Fields versions only: the Clef model or bounded Flash-to-Clef cascade that answered currency, service, payment status and row judgments. Optional Clairic amount reads are accounted in provider.",
"properties": {
"name": {
"enum": [
"@cf/cloudflare/clef-flash",
"@cf/cloudflare/clef",
"@cf/cloudflare/clef-flash+clef/uncertain-groups-v1"
]
},
"version": {
"const": "unreported"
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"version",
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
},
"groupingProvider": {
"type": "object",
"additionalProperties": false,
"description": "Measured optional grouping attempt, including a failed attempt that retains physical rows.",
"properties": {
"name": {
"enum": [
"@cf/moonshotai/kimi-k2.6"
]
},
"version": {
"const": "unreported"
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"version",
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
},
"rowGroups": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"firstRow": {
"type": "integer",
"minimum": 0,
"maximum": 1023
},
"lastRow": {
"type": "integer",
"minimum": 0,
"maximum": 1023
},
"anchorRow": {
"type": "integer",
"minimum": 0,
"maximum": 1023
},
"description": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"firstRow",
"lastRow",
"anchorRow"
]
}
},
"service": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"payment": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"externalId": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"last4": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
}
},
"required": [
"status",
"externalId",
"last4"
]
},
"rows": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"amount": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"textCid",
"promptVersion",
"headers",
"service",
"rows"
]
},
"extraction": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"enum": [
"not_required",
"extracted",
"incomplete"
]
},
"method": {
"enum": [
"provided_text",
"native_pdf",
"image_ocr",
"pdf_ocr"
]
},
"text": {
"type": "string",
"maxLength": 65536,
"description": "Returned only after source-document authorization; raw history contains annex references."
},
"textBytes": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance"
]
},
"derived": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string"
}
},
"required": [
"cid"
]
},
"pageCount": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 50
},
"locations": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"page": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 0
}
},
"required": [
"page",
"start",
"end"
]
}
},
"provider": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"version": {
"type": "string"
}
},
"required": [
"name",
"version"
]
},
"usage": {
"type": "object",
"additionalProperties": false,
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
},
"conversionTokens": {
"type": "integer",
"minimum": 0,
"description": "Estimated native conversion tokens, distinct from inference usage."
}
},
"required": [
"inputTokens",
"outputTokens",
"latencyMs"
]
}
},
"required": [
"status",
"method",
"textBytes",
"source",
"derived",
"pageCount",
"locations",
"provider",
"usage"
]
},
"classification": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentType": {
"enum": [
"invoice",
"receipt",
"agreement",
"statement_or_remittance",
"credit_or_correction",
"reminder",
"mixed",
"other",
"uncertain"
]
},
"probabilities": {
"type": "object",
"additionalProperties": false,
"properties": {
"invoice": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"receipt": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"agreement": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"statement_or_remittance": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"credit_or_correction": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"reminder": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"mixed": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"other": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"uncertain": {
"type": "string",
"description": "Decimal probability between 0 and 1."
}
},
"required": [
"invoice",
"receipt",
"agreement",
"statement_or_remittance",
"credit_or_correction",
"reminder",
"mixed",
"other",
"uncertain"
]
},
"model": {
"type": "string"
},
"modelVersion": {
"type": "string"
},
"promptVersion": {
"type": "string"
},
"confidence": {
"type": "string",
"description": "Distribution confidence, not calibrated accuracy or permission to act."
},
"invoiceRole": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"buyer",
"seller",
"neither",
"unclear"
]
},
"probabilities": {
"type": "object",
"additionalProperties": false,
"properties": {
"buyer": {
"type": "string"
},
"seller": {
"type": "string"
},
"neither": {
"type": "string"
},
"unclear": {
"type": "string"
}
},
"required": [
"buyer",
"seller",
"neither",
"unclear"
]
},
"confidence": {
"type": "string"
},
"promptVersion": {
"type": "string"
}
},
"required": [
"role",
"probabilities",
"confidence",
"promptVersion"
]
},
"usage": {
"type": "object",
"additionalProperties": false,
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 1
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
}
},
"required": [
"documentType",
"probabilities",
"model",
"modelVersion",
"promptVersion"
]
}
},
"required": [
"revision",
"startedAt",
"business",
"status",
"sources"
]
}
}
},
"required": [
"ingestionId",
"createdAt",
"status",
"uploads",
"revisions"
],
"x-relative-urls": [
"/uploads/primary/url",
"/uploads/original/url"
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}Example request
{
"name": "ingestions.resolve",
"input": {
"ingestionId": "ing_example",
"expectedProposalRevision": 1,
"expenseTargets": [
{
"contractId": "ctr_existing",
"activityKey": "expense"
}
]
},
"effective_at": "2026-09-01T00:00:00Z",
"idempotency_key": "ingestions.resolve-example-0"
}