documents.receive

Save exact document bytes as an immutable artifact. Identical bytes reuse the existing document; saving evidence alone creates no invoice, bill or payment.

What it does

Register exact bytes as an immutable typed artifact. Identity is CIDv1(raw, blake3); byte-identical content answers no_change with the existing documentId and cid in details. source_document accepts exact UTF-8 plain text or PDF bytes up to 10 MiB; it does not extract terms, establish acceptance or post money. image accepts exact PNG, JPEG or WebP bytes up to 256 KiB (never SVG): an issuer’s logo for accounts.register logoDocumentId.

Other kinds use their registered structured JSON schema, up to 256 KiB. externalId is optional for every kind. title is the founder word for the document (one line, at most 200 characters, stored trimmed); when omitted, a source_document is titled from its content — the first Markdown heading, the PDF’s /Title, or a JSON object’s title or name — and otherwise shown by its externalId. A title never changes an existing document: byte-identical content answers no_change and keeps the title it has.

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 documents.receive 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.

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.

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": "documents.receive"
    },
    "input": {
      "type": "object",
      "properties": {
        "kind": {
          "enum": [
            "source_document",
            "activity",
            "template",
            "contract",
            "activity_statement",
            "contract_lifecycle_statement",
            "image"
          ]
        },
        "contentBase64": {
          "type": "string",
          "minLength": 1,
          "maxLength": 13981016,
          "pattern": "^[A-Za-z0-9+/]+={0,2}$",
          "description": "The exact artifact bytes encoded as base64: at most 10485760 bytes for a source_document, 262144 bytes for the structured kinds."
        },
        "externalId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$",
          "description": "What the document is called, in the founder's words. Omit to take it from the content."
        }
      },
      "required": [
        "kind",
        "contentBase64"
      ],
      "additionalProperties": false
    },
    "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",
      "properties": {
        "documentId": {
          "type": "string",
          "minLength": 1
        },
        "cid": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "documentId",
        "cid"
      ]
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}

Example request

{
  "name": "documents.receive",
  "input": {
    "kind": "source_document",
    "contentBase64": "VmVuZG9yIGludm9pY2UgIzEyMzogVVNEIDEwMC4wMA==",
    "externalId": "vendor-invoice-123",
    "title": "Vendor invoice 123"
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "documents.receive-example-0"
}