Best Practices for Writing Feedback and Instructions

This guide helps you write effective feedback and custom field instructions for the Document AI service.

---

How Your Feedback Becomes Instructions

When you submit feedback, Document AI analyzes your instruction alongside the current document and automatically creates the appropriate type of instruction. Depending on what you're asking for, the system may create different kinds of instructions:

• Extraction guidance -- helps locate specific fields on documents. Best for telling the system where a field appears or describing its format. Example: "The invoice number is in the top-right corner, labeled 'Fakturanr'"

• Exact rules -- applies predictable, repeatable transformations such as calculations, date logic, or conditional field mapping. Example: "If the due date is missing, set it to the invoice date plus 30 days"

• Flexible rules -- handles complex adjustments that require interpretation, such as filtering, reformatting, or combining data. Example: "Exclude any line items that appear to be discounts or rebates"

You don't need to specify which type of instruction to create -- the system determines this automatically based on your feedback.

---

Feedback Text

Feedback creates instructions that are automatically applied when processing subsequent documents from the same source.

Writing Effective Feedback

Submit Feedback on a Relevant Document

When submitting feedback, use a document that actually demonstrates the problem. The system uses the document as context to understand your instruction.

• Good: Submit feedback on an invoice with a missing due date when asking to calculate due dates
• Bad: Submit feedback on an invoice that already has the correct due date

Be Specific and Actionable

❌ Weak	✅ Strong
"The vendor name is wrong"	"The vendor name should not include the address. Extract only the company name from the letterhead."
"Fix the line items"	"Split line items when there are multiple quantities on the same row. Each quantity should be a separate line."
"The date is incorrect"	"Use the 'Invoice Date' field, not the 'Delivery Date'. The invoice date appears in the top-right header."

Reference Document Elements Clearly

Describe where information appears in the document:

• "In the header section..."
• "From the footer on each page..."
• "In the line item table, the column labeled..."
• "The value next to the label 'Order No:'..."
• "On the first page, top-right corner..."

Describe Patterns, Not Single Instances

❌ Single Instance	✅ Pattern
"Change 'ABC Corp' to 'ABC Corporation'"	"Always use the full company name as it appears in the registration, not abbreviations"
"The amount should be 1,234.56"	"Use the 'Total Due' amount, not the subtotal. It's always in the bottom-right of the invoice summary."

Specify Data Transformations When Needed

• "Remove leading zeros from invoice numbers"
• "Convert unit prices from price-per-thousand to price-per-unit"

Choosing the Right Scope

The available scope values depend on which feedback endpoint you use:

Scope	Company-scoped endpoint	Tenant-scoped endpoint	Use When
Vendor	✅	✅	The rule applies only to documents from a specific vendor
Buyer	✅	✅	The rule applies to documents for a specific buyer/recipient
Company	✅	—	The rule applies to all documents within the company
Tenant	—	✅	The rule applies across all companies in your organization

• When submitting feedback through a company-scoped endpoint (/tenants/{tenantId}/companies/{companyName}/...), the broadest scope is Company.
• When submitting feedback through a tenant-scoped endpoint (/tenants/{tenantId}/...), the broadest scope is Tenant.

Note: Regardless of the scope value you choose, feedback is always scoped to the endpoint level. For example, using Vendor scope on a company-scoped endpoint applies the rule to that vendor within that company, while using Vendor scope on a tenant-scoped endpoint applies it to that vendor across all companies in the tenant.

Tip: Start with the narrowest applicable scope (Vendor or Buyer) and broaden only if the pattern is universal.

What to Avoid

• Vague complaints: "It's not working" or "This is wrong"
• Emotional language: "This is frustrating" doesn't provide guidance
• One-time corrections: "Change this invoice's date to March 15" -- describe the pattern instead
• Multiple unrelated issues: Submit separate feedback for each distinct problem
• Contradictory instructions: Ensure your feedback doesn't conflict with previous instructions

note

Feedback that is too vague, describes a one-time correction, or contains contradictory instructions may not result in an instruction being created. If this happens, try rephrasing your feedback to describe the general pattern you want applied to future documents.

Example Feedback

Example feedback (multi-line addresses):
The vendor address should be extracted as a single field with line breaks preserved. Currently it's being split across multiple fields.

Example feedback (localized labels):
Invoices from this vendor use 'Fakturanr' (Norwegian) as the invoice number label. Extract this field the same as 'Invoice Number'.

Example feedback (field mapping):
The 'Order Reference' field contains our internal PO number. Map this to the OrderNumber field, not the vendor's invoice reference.

Example feedback (multi-page documents):
This vendor includes a packing list as page 2. Only extract invoice data from page 1. Ignore the packing list.

Example feedback (line item calculations):
Each line item has a discount percentage in the 'Rabatt' column. Apply this discount to calculate the correct line amount.

Verifying and Troubleshooting Instructions

After submitting feedback, verify that the created instruction works as expected:

1. Reprocess one or more documents that should be affected by the instruction.
2. Check the applied instructions in the result -- when Document AI processes a document, instructions that modified the result are listed as applied instructions. Confirm that your new instruction appears.
3. Validate the output -- check that the extracted content matches your expectations.

If the instruction doesn't appear or the result isn't what you expected:

• Check the scope -- is the instruction scoped too broadly or too narrowly? A vendor-scoped instruction won't apply to other vendors, and a tenant-scoped instruction may affect more documents than intended.
• Look for conflicts -- review existing instructions to see if another instruction is overriding or contradicting your new one.
• Delete and rephrase -- delete the instruction and submit new feedback with clearer wording. Use the tips in this guide to be more specific about the pattern, conditions, and expected outcome.

---

Custom Field Specifications

Custom fields let you extract information beyond standard invoice fields. Custom fields can be defined at two levels:

• Header-level: Fields that appear once per document (e.g., project code, contract reference)
• Line-level: Fields that appear on individual line items (e.g., vehicle plate number, serial number)

Field Name

• Use clear, business-relevant names
• Avoid special characters
• Examples: Project Code, Cost Center, Approval Reference, Contract Number

Field Description

Describe what the field represents in business terms:

❌ Weak	✅ Strong
"A code"	"Internal project tracking code used for cost allocation, typically 6-8 alphanumeric characters"
"Reference number"	"Customer purchase order reference that our sales team uses to match invoices to orders"

Field Extraction Instruction

Tell the system how to find and extract the value. Include:

1. Location: Where does the value typically appear?
2. Label: What text labels or headers identify it?
3. Format: What does the value look like?
4. Fallback: What to do if not found?

Example:
Look for a field labeled 'Project' or 'Proj. Code' in the invoice header section, usually near the order reference. The value is a 6-character alphanumeric code starting with 'PRJ-'. If not present, leave empty.

Handle Edge Cases

Scenario	Instruction Approach
Field may not exist	"Extract if present, otherwise leave empty"
Multiple possible labels	"Look for 'PO Number', 'Purchase Order', or 'Bestillingsnr'"
Field in different locations	"Check header first, then footer, then line items"

Describe Value Format

Help identify valid values:

• "Numeric value, may include decimals"
• "Date in format DD.MM.YYYY or DD/MM/YYYY"
• "Alphanumeric, 8-12 characters"
• "Currency amount with thousands separator"

Complete Examples

Example field:
Name: Project Code
Scope: Header
Extraction instruction: Find the value labeled 'Project', 'Project Code', or 'Prosjekt' in the document header. Format is 'PRJ-' followed by 4 digits. May appear near the order reference.

Example field:
Name: Delivery Week
Scope: Header
Extraction instruction: Extract the week number from 'Delivery Week', 'Uke', or 'Week' fields. Value is a number 1-53. Usually in delivery details section.

Example field:
Name: Contract Reference
Scope: Header
Extraction instruction: Look for 'Contract', 'Agreement', 'Rammeavtale', or 'Kontrakt' followed by a reference. Usually in header near vendor information.

---

General Tips

1. Be consistent: Use the same terminology across related feedback and custom fields

2. One issue per feedback: Address a single extraction issue in each feedback submission

3. Use your business terminology: Reference fields using the terms your organization uses

4. Consider document variations: Write instructions that work across typical documents from that source

5. Review results: After providing feedback, check subsequent documents to verify the improvement