Document Processing

A customer uploads an electricity bill. Without document processing, someone has to open the file and copy the total and the issue date by hand, or check by eye that the bill is recent enough. Document processing does both: it extracts the values you ask for and checks them against what you expect, keeps the result with the file, and leaves to a person only what it could not settle.

In the API this feature is called processing (processing). The technical names are in the second half of this guide, under Technical reference.

Extraction and validation

The two parts are optional and independent. You can configure either one or both; when both are configured, they run together in a single reading of the file.

The button on each file says what it is going to do, according to what is configured:

Which files can be processed

Only files attached to a document whose data model has this configuration. A document is created by:

• an Ask for Document node, which always stores the file in a document of the type you choose;
• an Ask File node with Save to Entity on, entity Documents and, as the key, the key of the document data model;
• the customer portal;
• the API, with the document's key.

Files saved on an identity or an address of the customer, and files that a flow keeps only in a variable, cannot be processed. To process the file a flow asks for, set the node to also save it on a document.

PDF, JPG, JPEG, PNG, WEBP, HEIC and HEIF files are read, up to 30 pages each.

Extraction: the Details tab

Open Settings › Data models, choose a data model of type Document and stay on its Details tab. Below the model's details is the Document reading card, with Fields to extract: "Define the fields to extract from the document". It works like the Extract Information node of conversational flows: each row is a field, and Add field adds another.

For an electricity bill:

A Yes / No row is a question that the model answers by reading the document. "Is the amount due above 50 USD?" is not printed anywhere on the bill, so the answer comes with the sentence of the document the model relied on (for example TOTAL A PAGAR: $ 42,75), and the answer is only accepted when that sentence really is on the page. See Reading certainty.

The result of an extraction is a flat set of values, one per field, each with the page and the text of the document that backs it:

{ "valor_pagar": 42.75, "fecha_emision": "2026-10-15", "valor_mayor_50": false }

Extraction never says whether the file is valid. If the file is something else, such as an internet bill uploaded by mistake, extraction returns whatever it finds in it, which may be nothing.

There is no recognition step. With a single format and no description, which is what the Details tab creates, each file is read directly as this document, without first asking which document it is. To check that the file is the right one, add a Yes / No condition in the Validation tab (see below).

A field that is also validated shows the Validated chip. Removing it from Details leaves it in Validation.

Validation: the Validation tab

The Validation tab says what the document must meet: "If everything passes: Valid. If something fails: Not valid, with the reason. If something could not be read: To review."

Each condition has the same columns as a field to extract, with What to check instead of What to extract, plus one more: Expected. A condition does not need to be among the fields to extract.

• Add condition adds a Yes / No row expecting Yes, which is the most common case: a question about the document whose answer must be yes.
• Use a field from Details turns a field to extract into a condition too. It keeps its key, type and description, and you only choose what is expected. The field then shows Validated in Details.

What can be expected

A question answered by the model is the usual approach: "Does the deed authorize the representative to take on debt?" with Expected: Yes. The exact comparisons are there for the cases where the arithmetic must be guaranteed, such as an amount that decides a credit.

Checking that the file is the right document

There is no separate step for this: it is one more condition. The tab suggests it: "To check that the file is the right document, add a Yes or No condition, for example "Is the document an electricity bill?", with Expected: Yes."

For a company's articles of incorporation, the validation could be:

A deed in which the bylaws forbid taking on debt comes out Not valid, with the condition that failed, what the document says and where: "Not valid: puede_endeudar: expected Yes; the document says No (page 4)."

How the verdict is reached

• Valid when every condition is met.
• Not valid when any condition fails. The result names the first one, and how many more failed.
• To review when a condition could not be checked because its value was not found or was read with doubts. A value that could not be read never counts as met: a person decides.

Exists is the exception: a value that was not found in a complete reading fails the condition instead of leaving it to review. If the reading stopped halfway, the condition is left to review, because nobody can tell whether the value is there.

Questions that depend on today

For Yes / No, Text and List of values rows, the model is told today's date, so a question such as "Was the bill issued in the last 60 days?" is answered against the day of the reading. For Date and number rows it is never told, so that a missing date is never filled in with today.

"Today" is the date, in UTC, when the reading started. A later decision on the result does not change it.

Saving and testing

Both tabs edit the same configuration, and a bar fixed at the bottom of both saves it. It says All saved or Unsaved changes, and N values left to fill in when a row is incomplete; clicking it takes you to the first one, in whichever tab it is. Save writes both tabs at once and Discard undoes every change since the last save. Switching tabs does not lose what you typed.

Changing the configuration requires the configurations.write permission; without it, both tabs are read only. If someone else saved while you were editing, the save is rejected instead of overwriting their change: reload and apply yours again.

Test with a file, in the same bar, runs the configuration you are editing, even unsaved, against a file from your computer: a PDF or image of up to 4 MB and 30 pages. Nothing is saved and no customer is affected. The result reads exactly like the one on a real document, shows up to 10 pages starting with the ones where data was found, and warns when you changed the configuration after testing ("You changed the configuration after this test. Test again.") or when the test used unsaved changes.

When a condition compares with customer data, the test offers Customer data to compare with: No data, An existing customer or Test data. Use made-up data. Without a value to compare with, the condition is left To review, never Valid.

Advanced options

The Advanced options switch, in the Validation tab, shows the full configuration underneath the conditions:

• Show the Validate button on documents. If you turn it off, the buttons stop showing on documents, and saved results are kept.
• Accepted formats, when a document can arrive in several formats (for example, an electricity bill or a lease agreement as proof of address). Each format has a name and a description of how to recognize it, and each file is then first recognized as one of them, or as none.
• Requirements built with the rule editor (groups, negation, comparisons with another value of the document, and what happens when one fails: The file is not valid or Only warn), and Yes or No questions, which are answered in the result but never change it.
• Requirements that compare files of the same document, and For the document to be valid it must include.
• Minimum certainty, how dates and numbers are written in the document, and Edit as JSON.

Configurations saved before extraction and validation existed keep working exactly as they did, and nothing saved becomes unreachable. With the switch off, the tab says so: "This document has 1 requirement in Advanced options."

Processing a file

The actions appear in two places, on every file of a document whose data model has this configuration turned on:

• on the customer, under Entities › Documents;
• on a deal, under Documents › View Details.

They sit next to View and Download. Files of documents without a configuration look as they always did.

A reading can take up to five minutes for a file with many pages. You can close the page: the result is saved when it finishes. Only one file of the same document is read at a time; the others wait.

Under the result, Extract again, Validate again or Extract and validate again reads that file once more. If someone has already made decisions on it, the Hub asks first: "Read this file again?", "The decision taken on this file will be cleared." A file with too many pages, or of a type that cannot be read, is not offered again unless the configuration changed, because it would get the same answer.

Each file is read on its own, and reading one keeps the results of the others. After the configuration changes, each result says it was produced with an earlier configuration ("This file was validated with an earlier configuration."). Reading one of those files again leaves the rest out of the document's result, and the Hub shows them as not read until each one is read again.

Seeing a result requires the bc.attachments.read permission, because it includes images of the file.

Reading the result

With validation, the result starts with the verdict, in one sentence:

• "Valid."
• "Not valid: emitida_reciente: expected Yes; the document says No (page 2)." and, when there are more, "And 2 more conditions fail."
• "To review: numero_registro: it could not be read."

Then come the blocks:

• Extracted data: each field with its value and the page where it is. A Yes / No answer adds "Based on: «...»", the sentence of the document it relied on. A doubtful value says Uncertain reading, and one that is not in the document, Not found.
• Validation: a table with Field, Expected, Read, Result (Passes, Fails or To review) and Page.
• Other requirements and Yes or No questions, when the configuration has them in Advanced options.
• The document page, with the box of each value marked. Selecting a value takes you to its page.

With extraction only, there is no verdict line and the words Valid and Not valid never appear.

Files that could not be read

When the configuration has several formats in Advanced options, a file that matches none of them says "Not valid: the file is not «Electricity bill»." if there are validation conditions, or is left To review if there are not.

Deciding what is left to review

Each case has its own buttons, and the text of the button says what will happen:

Every decision asks for a Reason and is saved with who made it and when. Change decision lets you correct it. The status of the file is recomputed on the spot. When a value is accepted, the conditions that depend on it are checked again with the date of the original reading.

From a conversational flow

The Ask for Document node asks the customer for a file, stores it in a document of the type you choose and, with Validate the document on, processes it with this configuration as soon as it arrives. Two modes:

• Continue without waiting. The conversation moves on and the result appears on the file's row, like any other.
• Wait for the result. The conversation waits for the verdict of the files it just received, up to 6 minutes, and continues through Valid, Not valid, Needs review or Could not be validated. It needs validation rules: a type that only extracts data has no verdict to wait for.

Technical reference

This part is for anyone who integrates through the API or needs to know exactly how each result is computed.

Names in the Hub and in the API

The same configuration as JSON

The electricity bill with three fields to extract and three conditions, as PUT /v1/data-models/{dataModelId}/processing receives it. The single format has no description, so there is no recognition step:

{
  "documentTypes": [
    {
      "key": "planilla_luz",
      "label": "Planilla de luz",
      "fields": [
        { "key": "valor_pagar", "type": "number", "description": "Total a pagar de la planilla" },
        { "key": "fecha_emision", "type": "date", "description": "Fecha de emisión",
          "purpose": "both", "expected": { "op": "after", "value": "2026-09-01" } },
        { "key": "valor_mayor_50", "type": "boolean", "description": "¿El valor a pagar es mayor a 50 USD?" },
        { "key": "ciudad", "type": "string", "description": "Ciudad del suministro",
          "purpose": "validation", "expected": { "op": "one_of", "value": ["Quito", "Guayaquil"] } },
        { "key": "emitida_reciente", "type": "boolean", "description": "¿La planilla fue emitida en los últimos 60 días?",
          "purpose": "validation", "expected": { "op": "is_true" } }
      ]
    }
  ]
}

What the server stores is the same plus what it derives: each condition becomes a blocking validation named __expected_<field>, and documentRules.unrecognizedFiles becomes invalid. Both are managed by the server: they are dropped from any body you send and computed again, so reading the configuration and saving it back gives the same result. The Data Models API describes every key.

How a file is processed

For each file:

1. Reading. PDFs are rendered page by page; an image is one page. A file of more than 30 pages is not read (too_large).
2. Recognition, only when the configuration has several formats or a format with a description (Advanced options). One call to the model decides the format from the descriptions, or answers that none fits (unclassified). With a single format and no description, the file is taken as that format directly.
3. Extraction. The model is asked for the values of every row, those of Details and those of Validation. If some are missing, it is asked again for those only, up to three attempts in total. What was already found is kept. If the AI provider rejects the request or time runs out, extraction stops with what it has and the file is partial (partial: true).
4. Interpretation of each value by its type.
5. Cross-check of each value, or of the sentence the model quoted, against the file with a second, traditional reading.
6. Certainty of each value.
7. Evaluation of conditions, requirements and questions, and then of the status of the file and of the document.

The model is asked to copy text, numbers and dates exactly as printed. Turning $ 1.234,50 into 1234.5 or 08/10/2026 into a date happens afterwards, with fixed rules. A receipt that only prints March 2024 gives an empty date, never an invented day. What is expected never reaches the model: the question is asked without its answer.

Reading certainty

Each value gets a certainty (confidence) between 0 and 1, built from checks that do not depend on the model's opinion of itself. There are two ways to check a value, and confidenceBreakdown.basis says which one was used.

By the value (basis: "value"), for numbers, dates and text printed on the document:

certainty = 0.25 × location + 0.5 × match + 0.25 × format

By the quote (basis: "quote"), for every Yes / No answer, and for a text whose value does not appear in the sentence the model quoted (an answer the model worked out, not one it copied). What is checked is the quoted sentence (sourceText): first in the box, and if it is not there, in the whole page. The formula is the same, with the match of the quote instead of the value, and with one more cap: a quote that is not found on the page, or a missing quote, leaves the certainty at 0.45 at most. Numbers and dates are always checked by the value, because a misread amount must still be caught.

Two caps apply in both cases: a value that could not be cross-checked at all never goes above 0.6, and one that cannot be interpreted never goes above 0.3. Below its minConfidence (0.7 by default, or 0.5 for Yes / No) the value is needs_review; a value that was not found is missing.

When there is a recognition step, the format also gets a certainty: 0.5 + 0.5 × (required values read correctly ÷ required values), counting every value when none is required. Below its minConfidence (0.6 by default) the file is left to review. Without a recognition step, it is 1.

Evidence

Each reading stores the images of the pages and a crop around every value that has a box. When the evidence of a reading is very large, pages without values are dropped first. Image links expire after 60 minutes; the Hub asks for new ones on its own.

Evidence lives as long as its result: a new reading of the same file replaces it, and deleting the file deletes it too.

Statuses and reasons

A file is:

• invalid when it could not be opened, a condition or a blocking requirement failed, a required value of an older configuration is missing, someone rejected its format, or, with validation conditions, it matches none of the formats.
• needs_review when a condition or a blocking requirement could not be checked, a required value needs review, its format is doubtful, it has more than 30 pages or the reading failed. Without validation conditions, a file that matches no format is also left to review.
• excluded when someone ignored it.
• valid otherwise.

With extraction only, this status is still computed but it is not a verdict: the Hub shows the extraction status instead, and the API returns it in extraction.status.

The document also has a status, which the API returns in summary: valid when acceptedTypes is met with valid files and no blocking requirement across files fails or is left unchecked; needs_review when it would be met counting the files still to review or the files that were not read, which could be of any format; and invalid otherwise. Ignored files do not count. The Hub shows each file on its own and does not show the status of the document.

Every status other than valid comes with reasons, each with a code and, where it applies, the key of the value, the condition or the format:

For a condition, key is __expected_<field>.

Manual review

unreadable and unsupported files cannot be reviewed.

Approving or rejecting a value or a format re-checks the conditions that depend on it, with the date of the original reading. A new decision on the same item replaces the previous one. Reading a file again replaces its decisions, and any reading replaces the decisions on requirements across files, because the evidence changed. Replaced decisions stay in the history. Results produced with an earlier configuration cannot be reviewed; read the file again first.

Rules (Advanced options)

The requirements and questions of Advanced options are rule trees built from three kinds of node:

Node   = Group | Not | Rule
Group  = {"all": [Node, ...]}  or  {"any": [Node, ...]}
Not    = {"not": Node}
Rule   = {"field": Operand, "operator": Operator, "value": Literal or Reference, "threshold": number}

Each node has exactly one of all, any, not, or the keys of a rule. A single rule is also a valid tree. A tree allows at most five levels and 50 rules. value is required or forbidden depending on the operator; only similar_to accepts threshold.

A rule's field is fecha_emision (a value of the same format, from the file being evaluated) or planilla_luz.fecha_emision (a value of another format, taken from another file of the same document; requirements across files always use this form). value is a fixed value (dates as "YYYY-MM-DD") or a reference:

When a value comes from another file, the best candidate of that format is used: an ok one before one to review, and then the one with the highest certainty. Files with a rejected format and ignored files are never used. Identities marked as sensitive cannot be referenced: the save is rejected.

Three-valued evaluation. Each rule answers true, false or unknown, and groups combine them without turning unknown into a false answer: all is false if any child is false, else unknown if any is, else true; any is true if any child is true, else unknown if any is, else false; not swaps true and false. A condition, requirement or question that ends unknown is inconclusive, with the reason:

exists, not_exists, is_empty and is_not_empty are the exception: on a value that was not found they answer (absent counts as empty), unless the reading stopped early.

What they mean for documents:

• equals on text ignores case, accents and repeated spaces, but not punctuation. Two numbers are equal if they match up to rounding; two dates, if they are the same day.
• contains, starts_with, ends_with and in_list compare text the same way as equals. On a list, contains is true when any of its items equals the value.
• within_last_days N is true when the date is between N days ago and today, both included; a future date does not count. older_than_days N, when it is more than N days old. is_current, when it is today or later; has_passed, when it is before today.
• similar_to scores two texts from 0 to 1, without accents, case or punctuation, and is true from threshold up (0.85 by default). A name whose words all appear in the other scores high: Juan Perez against Juan Carlos Perez Gomez gives 1.0.

Reading numbers and dates

Numbers follow format.numberFormat:

Thousands groups must have exactly three digits. A Whole number with decimals, such as 1.234,56, is not read: the digits are never glued into 123456.

Dates follow format.dateOrder (auto, dmy, mdy, ymd). Dates with the month spelled out are read in Spanish and English (08 de octubre de 2026, Oct 8, 2026). 10/08/26 with auto reads as 2026-08-10, flagged as ambiguous. An incomplete date (March 2024) or one that does not exist (31/02/2026) is not read, and is never completed with today's day, month or year. A value that cannot be read keeps the copied text, gets 0 for format and its conditions are left to review.

Through the API

The first two are described in the Data Models API and the other three in the Documents API. The document list also returns processingStatus, the status of the document after decisions, or null when no file was ever read.

Every save that changes the formats, the rows or the rules increases definitionVersion. Results remember which version produced them, so the Hub warns when a result is older than the current configuration.

Limits of this version

• In a conversation, only through Ask for Document. It is the node that can wait for the verdict and branch on it; see From a conversational flow.
• One file at a time in the Hub. There is no button to process every file of a document at once, and the Hub does not show the status of the document as a whole. The API can process up to 20 files per call.
• Only document files. Files on identities or addresses, and files kept only in a flow variable, are not processed.
• Supported files: PDF, JPG, JPEG, PNG, WEBP, HEIC and HEIF. Others are listed as unsupported and do not count. Files embedded inside a PDF are not read.
• Size: 30 pages per file. The test in the Hub accepts files of up to 4 MB (20 MB through the API) and shows at most 10 pages, those with values first.
• Configuration size: up to 40 rows per format, adding Details and Validation; up to 50 conditions and requirements together per format, 50 questions per format, 20 formats, 50 conditions per rule tree, five levels of groups and 200 values in a list.
• No tables. The rows of a table cannot be read yet.
• No protected data. Identities marked as sensitive are never used in a comparison.
• Deal documents. A document that belongs only to a deal has no customer to compare with, so a condition that expects a customer value is left to review.
• Waiting. Reading a file with many pages can take several minutes. If time runs out, the values it did not reach are left unread and the file can be read again.
• Uploads during a reading. If a file is uploaded to the same document while another is being read, the result of that reading may not be kept. The Hub then shows the file as not read; read it again.