Ask for Document

Ask for Document asks the customer for a file — a utility bill, a bank statement, a company's articles of incorporation — and stores it in the customer's document of the type you choose. It can also have the file validated with the rules of that document type, and either move on while the validation runs in the background or wait for the result and continue through a different output for each verdict: Valid, Not valid, Needs review or Could not be validated.

It is in the User Input group of the editor palette and runs on the same engine as Ask File: the request, the invalid-file message, multiple files and the WhatsApp finish button behave the same. The difference is the destination. Ask File can store the answer in a variable, an identity, an address or a document, or nowhere on the customer's record; Ask for Document always stores it in a document of the chosen type, which is what makes the validation possible. Use Ask File when the file belongs somewhere else, and Ask for Document when it is a document you want on the customer's record and, usually, checked.

Configuration

Document name, Clear All Attachments, Multiple files, Save to Variable and Metadata work as in Ask File, including the behavior per channel of batches.

Validation

Validate the document runs the document processing configured on the document type: the fields to extract from the Details tab and the conditions of the Validation tab. What changes is whether the conversation waits for it.

Continue without waiting

The validation runs in the background and the conversation does not wait for the result: it continues through the node's output as soon as the file is stored. The node keeps its two outputs, Success and the error output. The result stays with the file in the customer's documents in the Hub, like any other processing result. The canvas shows the badge Validated without waiting.

Any document type with validation can use this mode, including one that only extracts data.

Wait for the result

The conversation waits for the validation of the files the customer just sent, up to 6 minutes, and continues through the output that matches the verdict. The canvas shows the badge Waits for the result and four outputs.

This mode is only offered when the document type has validation rules (required fields or conditions in the data model's Validation tab). A type that only extracts data has no verdict to wait for, so it can only Continue without waiting. Turning on Validate the document for a type that allows waiting selects Wait for the result by default.

The verdict is about the files this node received, never about what the document already had: an older valid file in the same document does not make a new one valid. The files are judged together the way the document type judges a document, so with several files the verdict is about the set; with the default rules one valid file is enough. See Statuses and reasons in the processing guide.

What the customer sees while waiting. As soon as the files are stored, the node sends the Message while validating. When the result arrives the conversation continues on its own through the matching output; the customer does not need to write anything. If the customer writes in the meantime, the result is applied right away when it is ready; otherwise the node sends the Message while validating again. A file sent during the wait is not stored in the document and does not count for the verdict.

Asking again on Not valid. Attempts counts the times the customer sends the document. While attempts are left, a Not valid result sends the Message to ask for it again as a new file request, and the next file the customer sends starts the next attempt. The files of earlier attempts stay in the document (Clear All Attachments applies only to the first attempt) and are judged together with the new ones, so the new file only has to make up for what was missing. When the last attempt is not valid, the node leaves through Not valid. Needs review and Could not be validated never ask again.

Only PDFs and images are validated. PDF, JPG, JPEG, PNG, WEBP, HEIC and HEIF. While waiting, any other file is not stored in the document: if it was the only file, the customer gets the Invalid Message and is asked again without spending an attempt; if it came with other files, only those are validated. Say in the Upload Message that you expect a PDF or a photo. Without waiting, such a file is stored but not validated, and the node leaves a notice.

Inactivity does not end the wait. While the conversation waits for the result, its inactivity timeout and inactivity follow-ups are postponed until the wait ends.

An agent can take over. If an agent takes the conversation while it waits, the result is still saved in the validation result variable, but the flow does not move; a notice records it.

Switching between modes

Switching to Wait for the result creates Not valid and Needs review and connects them wherever the main output already went, so the flow keeps going to the same place until you rewire them. Could not be validated is the node's error output and keeps its own connection.

Switching to Continue without waiting, or turning Validate the document off, removes Not valid and Needs review together with their connections. If they reached nodes that the main output does not, the editor lists them in a confirmation dialog, "Connections will be lost", before applying the change. The waiting options (messages, attempts, result variable) are kept while you stay in the editor, so switching back restores them.

The Validation Result Variable

With Save the validation result, the node writes an object variable before leaving and before every new request on Not valid:

{
  "status": "invalid",
  "reasons": [{ "code": "accepted_type_invalid", "key": "recibo_luz" }],
  "files": [
    {
      "attachmentId": "att_3f9a1c",
      "status": "invalid",
      "reasons": [{ "code": "blocking_validation_failed", "key": "__expected_es_recibo" }]
    }
  ],
  "attempt": 1,
  "documentId": "doc_8b2e47",
  "attachmentIds": ["att_3f9a1c"]
}

The variable carries codes and keys only, never an extracted value or a file name. In a Conditional, result.status reads the status of a variable called result (see Variables).

Output Handles

Invalid input never fires an output: text, an unsupported media type or a premature "Listo" get the Invalid Message and the node keeps waiting.

Behavior per Channel

Web. The customer picks the files and sends them once; with Wait for the result, the waiting message and later the next node's messages appear in the same chat.

WhatsApp. Files arrive one by one, as in Ask File. With Multiple files and Wait for the result, the wait starts when the batch closes: the customer reaches the File limit or taps the finish button. A file that is not a PDF or an image is refused when it arrives.

Email. The editor does not offer this node in email flows. If a flow built another way reaches it on email, the files are stored (and validated in the background if Validate the document is on), but email cannot wait for the result: a node set to Wait for the result leaves through Could not be validated, with channel_cannot_wait in the result variable.

Publish Gate

Publishing is blocked when:

• No document type is chosen: "Pick the document type the file is stored in".
• Validate the document is on with Multiple files and the File limit is empty or outside 1 to 20.
• Attempts is not a whole number of 1 or more.
• The node waits for the result and Not valid is not connected: without it, a document that is not valid leaves through Could not be validated.
• The node waits for the result and Could not be validated is not connected: without it, the conversation ends when the validation fails or does not answer in time.
• The node is saved with Wait for the result but the document type has no validation rules, so it would never wait.
• The variable in Save to Variable does not match Multiple files, or a node downstream that reads one file points at this node's variable while Multiple files is on (the same rules as Ask File).

It warns, without blocking, when:

• Needs review is not connected: that verdict leaves through Could not be validated.
• Not valid or Needs review keeps a connection while the node does not wait: that connection is never followed.
• Validate the document is on but the document type has no validation enabled: the file is stored without validation.
• The document type is no longer in Data Models: the node keeps storing files under that key until you pick another type.

See Publish Gate for the rest of the checks a flow must pass.

Notices This Node Can Leave

Notices appear in the conversation's notices panel in Chat and aggregated per flow and node in Flow Notices. The node leaves the same notices as Ask File for the file request itself (answer_unresolved, entity_without_customer, files_over_limit, unsupported_media_type, node_warning, node_failed); see Ask File. These are its own:

When to Use It

Proof of address that must be recent. A document type "Utility bill" with the condition "Was the bill issued in the last 60 days?" expecting Yes. Wait for the result with 2 attempts: Valid continues the onboarding, Not valid offers a human agent, Needs review tells the customer someone will check it, Could not be validated stores the case for a manual follow-up.

Documents for later review. Bank statements that an analyst will read: Continue without waiting stores and validates them in the background, and the customer is not kept waiting.

Only storing. With Validate the document off, the node is a simpler Ask File that always files the answer in the right document, and Save the document ID passes that document on to the next nodes.

Things to Know

There must be an identified customer. The document belongs to a customer: put a Login or a Create Borrower before this node. Without a customer the file is not stored in any document; with Wait for the result the node leaves through Could not be validated.

Six minutes is a ceiling. Reading a file with many pages can take several minutes, so write the Message while validating for a customer who may wait that long.

Not valid is retried, the rest is not. Only a Not valid verdict uses up attempts. A failed reading or a timeout leaves through Could not be validated at once.

The verdict ignores what the document had before. Each run of the node judges only its own files. To start from an empty document every time, turn on Clear All Attachments.

Clear All Attachments is permanent. The document's existing files are deleted before the new ones are stored.