> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affinda.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.affinda.com/feedback
```json
{
"path": "/academy/solution-design",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Integration workflows and solution design patterns
> Compare integration workflow patterns for connecting Affinda to your existing document processing pipelines, including API, email, and ATS integrations.
## Purpose
The Affinda Platform is designed to flexibly integrate into a wide range of document processing workflows. We understand that every customer’s internal systems, validation rules, and exception handling processes are different.
This guide outlines a framework to help you choose the most suitable integration workflow that fits your use case. It presents six common integration patterns used by customers today, each representing a distinct way to manage the flow of documents, data, and decisions between your system and Affinda.
The workflows presented cover some of the common setups in production, but they are not intended to be exhaustive. Depending on the use case, customers may need to adapt or extend them. For additional details, check out the FAQs at the bottom of this article or book a quick consult.
## Workflow criteria
Your solution design will heavily depend on the answer to two key questions.
### Q1. Will any exceptions be reviewed in Affinda’s UI?
Exception handling requires users to review any documents that fail validation logic and manage the steps needed to correct them. This may occur within Affinda via our validation interface, or entirely within your system using custom workflows or user interfaces.
### Q2. Will any validation or mapping logic be completed inside Affinda?
Validation logic refers to the business rules used to decide whether the extracted data is complete, correct, or acceptable. This could be implemented by:
* Implementing within the Affinda Platform using our validation rule and data mapping capabilities (see our tutorial on [Straight-Through Processing](/academy/straight-through-processing) for more information)
* By implementing this logic in your system
In cases where rules are applied in your system, the results of these validation checks can be sent back into the Affinda Platform for the exception handling process.
“Rules” refers to any logic that auto-confirms fields or raises warnings where requirements are not met (e.g., supplier match exists, totals match).
## Workflow Summary Table
| ID | Workflow name | Q1. Exceptions | Q2. Validation | Explanation |
| :----- | :-------------------------------------------------------- | -------------- | --------------------------- | :-------------------------------------------------------------------------- |
| **W1** | No validation | No | No | Upload → get JSON. No rules, no human in the loop. |
| **W2** | Client-side validation | No | No | Same as W1, however, customer applies rules once data has been exported. |
| **W3** | Affinda validation logic | No | Yes - rules live in Affinda | Affinda validates automatically; no human review. |
| **W4** | Review all documents in Affinda | Yes | No | Humans review every doc in Affinda UI; no automated rules. |
| **W5** | Client-side validation with exception handling in Affinda | Yes | Yes - rules owned by client | Your rules, pushed back as warnings; flagged docs reviewed in Affinda. |
| **W6** | Validation logic & exception handling in Affinda | Yes | Yes - rules live in Affinda | Affinda validates; flagged docs reviewed in Affinda for final confirmation. |
In some cases, the validation interface can be embedded within a client's system to assist with exception handling. See [Embedded Mode](/reference/embedded) to learn more, or discuss with Affinda to learn how to enable this.
## Detailed overview
The below provides detailed explanations of each of the workflow options.
Unless explicitly stated, all workflows assume that webhooks are used to notify your system when a document is ready for the next step. If webhooks aren’t feasible in your environment, synchronous polling or scheduled checks can be used as alternatives but may introduce latency or additional complexity.
This is the simplest workflow: documents are uploaded, parsed, and data is retrieved as-is with no further validation or review. It’s ideal when the extracted fields are either low-risk or used only as a starting point for downstream systems. It offers the fastest turnaround and minimal integration effort.
### API integration
1. `POST /document`
2. `webhook: document.parse.completed`
3. `GET /document`
Follows the same workflow and integration with Affinda as W-1, however, validation rules and/or user review occurs in the client system after the data has been exported. These rules and user review does not get sent back to Affinda.
### API integration
1. `POST /document`
2. `webhook: document.parse.completed`
3. `GET /document`
Here, Affinda handles parsing and validation, but all exception handling takes place in your system. Documents that fail your rules are flagged for manual review in your own user interface or workflow engine. This gives you complete control over the review experience while still leveraging Affinda’s validation logic. It’s a good fit for teams that already have internal exception queues or don't want users to manage multiple platforms.
### API integration
1. `POST /document`
2. `webhook: document.validate.completed`
3. `GET /document`
* Use `GET /allvalidationresults` to get results for each field, else use `isConfirmed` from the document response to determine if the document needs exception handling
In this workflow, all documents are validated by a user within Affinda. This is a good fit for customers who want all documents to undergo some form of user validation. It can often be used as an intermediary step to validate the accuracy of the data before enabling straight-through processing of documents without any user intervention.
### API integration
1. `POST /document`
2. `webhook: document.validate.completed`
3. `GET /document`
In this pattern, Affinda performs the initial extraction, and the data is sent to the customer’s system. Validation occurs within the client’s system and any documents failing validation logic are then reviewed by users within Affinda.
This is well-suited for teams that want to keep humans in the loop using Affinda's validation interface, but want to use their own systems to run validation logic across documents. This may be because either:
* Validation logic is already built and do not want to move this across into the Affinda Platform
* Have a high amount of reference data needed for validation
* They prefer not to build their own correction interface
It’s a good balance between automation and control, especially for medium-volume workflows with variable document quality.
### Updating results in Affinda
The two most common ways to send failed validation results created in your system are:
1. **Field validation results:** Add field-level warnings explaining why they have failed validation.
2. **Warnings:** Add a document-level message explaining which fields need attention (see image below).
Documents that have passed all validation results and do not need any exception handling ior user validation should be updated so that their status is set to 'Confirmed.
### API integration
1. `POST /document`
2. `webhook: document.parse.completed`
3. `GET /document`
4. `PATCH / document (`add `warningMessages`) or `POST /validation-results/batch-create-validation-results` (see 'Updating results in Affinda' above)
5. `webhook: document.validate.completed`
6. `GET /document`
7. `PATCH /document` (`isConfirmed` set to true)
This fully automated workflow waits until a document is 'confirmed' within Affinda (either automatically or via user review), then triggers a webhook for your system to collect the final data.
It requires no intervention or mid-process interaction from an integration perspective, making it ideal for high-volume pipelines.
### API integration
1. `POST /document`
2. `webhook: document.validate.completed`
3. `GET /document`
## External reference data
### Global data
Many teams will have a master list of data that they want to map the extracted data to - this is known as a [Data Source](/configuration/picklists) in Affinda. This reference data can be added by uploading a flat-file via the platform, or by adding and updating via API. This global reference data is managed separately from the document upload and export flow, and the matching of raw data to reference data occurs within the document processing.
### Document specific data
Occasionally, teams will need to inject data per document. This may be needed where additional data specific to that document (but not present on the document itself) is needed for validation (e.g., the user submitting the file to the client system specifies the expected value of the document, and this is matched against the extracted data).
In this case, customers should patch the data to the document as part of either W3 or W6.
## FAQs
Data mapping is independent of the chosen workflow. You’ll still need to align Affinda’s extracted field names and values to your internal data model (e.g. supplier lists or GL codes) regardless of how you manage validation or exceptions.
Yes, if you patch fields after parsing, you must explicitly trigger rule re-evaluation to get updated validation results. Skipping this step may cause documents to remain unconfirmed or reflect outdated logic.
Technically yes. Some systems route documents differently based on type, volume, or confidence thresholds. However, maintaining multiple flows increases complexity and should be considered only when the benefit clearly outweighs the overhead.