# ingestions.invoice_candidates

Read source-backed invoice field candidates from a completed document extraction. Returns suggestions only; does not record an invoice or payment.

## What it does

Discover canonical invoice source candidates from exact retained complete extraction text. Returns UTF-8 spans; header and amount choices are v0, v1, etc. in array order. Rows must all be addressed, including summaries and other numeric rows. Use these choices with ingestions.resolve for explicit caller corrections. Returns a transient read-only result without a durable command receipt or proposal, financial or processing change. Requires the complete source/context read footprint. Maximum 64 KiB text, 254 candidates per field and 64 numeric rows.

## 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.invoice_candidates` 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](/docs/api/) 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"`. |
| `invoiceText` | string | Yes |  Maximum length: `65536`. Example: `"Exact retained extraction text"`. |

## 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 |
|---|---|---|---|
| `proposalRevision` | integer | Yes |  Minimum: `1`. Maximum: `8`. |
| `textCid` | string | Yes |   |
| `candidates` | object | Yes |   |
| `candidates.headers` | object | Yes |   |
| `candidates.headers.vendor` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.headers.vendor[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.vendor[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.vendor[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.headers.buyer` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.headers.buyer[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.buyer[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.buyer[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.headers.externalId` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.headers.externalId[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.externalId[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.externalId[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.headers.date` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.headers.date[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.date[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.date[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.headers.currency` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.headers.currency[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.currency[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.currency[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.headers.total` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.headers.total[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.total[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.headers.total[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.rows` | array | Yes |  Items: object. Maximum items: `64`. |
| `candidates.rows[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.rows[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.rows[].text` | string | Yes |  Maximum length: `65536`. |
| `candidates.rows[].amounts` | array | Yes |  Items: object. Maximum items: `254`. |
| `candidates.rows[].amounts[].start` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.rows[].amounts[].end` | integer | Yes |  Minimum: `0`. Maximum: `65536`. |
| `candidates.rows[].amounts[].text` | string | Yes |  Maximum length: `65536`. |


[All commands](/docs/command-reference/) · [Operation and errors](/docs/api-reference/operations/commands-execute/) · [Reusable schemas](/docs/api-reference/components/)

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

## Exact request schema


```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "const": "ingestions.invoice_candidates"
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "ingestionId": {
          "type": "string"
        },
        "invoiceText": {
          "type": "string",
          "maxLength": 65536
        }
      },
      "required": [
        "ingestionId",
        "invoiceText"
      ]
    },
    "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


```json
{
  "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": {
        "proposalRevision": {
          "type": "integer",
          "minimum": 1,
          "maximum": 8
        },
        "textCid": {
          "type": "string"
        },
        "candidates": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "headers": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "vendor": {
                  "type": "array",
                  "maxItems": 254,
                  "items": {
                    "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"
                    ]
                  }
                },
                "buyer": {
                  "type": "array",
                  "maxItems": 254,
                  "items": {
                    "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"
                    ]
                  }
                },
                "externalId": {
                  "type": "array",
                  "maxItems": 254,
                  "items": {
                    "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"
                    ]
                  }
                },
                "date": {
                  "type": "array",
                  "maxItems": 254,
                  "items": {
                    "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"
                    ]
                  }
                },
                "currency": {
                  "type": "array",
                  "maxItems": 254,
                  "items": {
                    "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"
                    ]
                  }
                },
                "total": {
                  "type": "array",
                  "maxItems": 254,
                  "items": {
                    "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"
                    ]
                  }
                }
              },
              "required": [
                "vendor",
                "buyer",
                "externalId",
                "date",
                "currency",
                "total"
              ]
            },
            "rows": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "object",
                "properties": {
                  "start": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 65536
                  },
                  "end": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 65536
                  },
                  "text": {
                    "type": "string",
                    "maxLength": 65536
                  },
                  "amounts": {
                    "type": "array",
                    "maxItems": 254,
                    "items": {
                      "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"
                      ]
                    }
                  }
                },
                "required": [
                  "start",
                  "end",
                  "text",
                  "amounts"
                ]
              }
            }
          },
          "required": [
            "headers",
            "rows"
          ]
        }
      },
      "required": [
        "proposalRevision",
        "textCid",
        "candidates"
      ]
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

## Example request


```json
{
  "name": "ingestions.invoice_candidates",
  "input": {
    "ingestionId": "ing_example",
    "invoiceText": "Exact retained extraction text"
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "ingestions.invoice_candidates-example-0"
}
```