> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.affinda.com/feedback

```json
{
  "path": "/reference/upload-options",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Document upload options for the API

> Compare options for uploading documents to the Affinda API, including multipart file uploads, URL-based ingestion, base64 payloads, and async processing.

While a range of API endpoints drive the Affinda solution, uploading documents for processing (and receiving the response) is fundamental to the platform.

## Submission and Retrieval Options

When integrating document data extraction (parsing), there are three primary ways to submit documents and retrieve the parsed data:

<AccordionGroup>
  <Accordion title="Synchronous Parsing (wait=true)">
    **Explanation:**

    * Users submit a document, and the API processes it immediately
    * User application waits and the request stays open (`wait = true` ) until parsing is complete
    * When finished, the API directly returns the parsed document data

    **Pros:**

    * Simplest integration
    * Immediate retrieval of results after completion
    * Suitable for documents that need to be processed quickly

    **Cons:**

    * Not suitable for large documents or high-volume scenarios
    * Can lead to timeouts for documents requiring lengthy processing

    **Ideal Use Case:**

    * Interactive apps where quick, synchronous response times are critical
  </Accordion>

  <Accordion title="Asynchronous Parsing with Polling (wait=false)">
    **Explanation:**

    * Users submit a document and receive an immediate acknowledgment (document ID)
    * User application periodically checks (polls) the API endpoint using repeated GET requests to determine when parsing is complete
    * Once processing finishes, user retrieves the parsed data.

    **Pros:**

    * Avoids connection timeouts; ideal for longer or variable processing times
    * Better suited for handling multiple simultaneous document submissions

    **Cons:**

    * Additional complexity with polling logic
    * Generates higher API call volume (frequent polling checks)
    * Slight delay between actual completion and data retrieval, depending on polling interval

    **Ideal Use Case:**

    * High-volume scenarios, large documents, or batch processing jobs where exact completion timing isn't critical.
  </Accordion>

  <Accordion title="Asynchronous Parsing with Webhooks (resthook)">
    **Explanation:**

    * Users submit a document, receiving an immediate acknowledgment
    * Rather than polling, your application receives a webhook (callback notification) directly when the document is ready for export
      * In some cases this will be when the document is finished parsing, but in other use cases this may be when the document has been validated
    * After receiving the webhook, your application retrieves the parsed data with a GET request.

    **Pros:**

    * Most efficient asynchronous method—reduces unnecessary polling.
    * Lower overall API usage
    * Provides real-time notifications upon completion

    **Cons:**

    * Slightly higher setup complexity (webhook listener infrastructure required)

    **Ideal Use Case:**

    * Real-time workflows or event-driven architectures where timely data retrieval is essential, or API usage optimization is needed
    * Scenarios where the application must wait until the document has been fully validated before receiving results

    See [<u>Webhooks</u>](https://docs.affinda.com/docs/webhooks) for more information.
  </Accordion>
</AccordionGroup>

## Request Body

The following parameters may be included in the API POST request to Affinda using the [<u>Upload a document for parsing</u>](https://docs.affinda.com/reference/createdocument) endpoint.

Note, all individual parameters are optional, however, one of the following must be specified:

* File
* URL

Documents should be uploaded to the relevant `Workspace` (and optionally `documentType` specified if the document type is known at upload).

<Expandable title="Request Parameters">
  <ParamField body="file" type="file">
    File as binary data blob. Supported formats: PDF, DOC, DOCX, XLSX, ODT, RTF, TXT, HTML, PNG, JPG, TIFF, JPEG.
  </ParamField>

  <ParamField body="url" type="string | null">
    URL to a document to download and process
  </ParamField>

  <ParamField query="workspace" type="string">
    Unique identifier for the Workspace to upload the document to. The identifier can be found by either using the Get list of all workspaces endpoint or through the app
  </ParamField>

  <ParamField query="documentType" type="string | null">
    Unique identifier for the Document Type to upload the document to. If specified, Workspace must also be specified. Used when the document type is known.
  </ParamField>

  <ParamField query="wait" type="boolean">
    If "true" (default), will return a response only after processing has been completed. If "false", will return an empty data object which can be polled at the GET endpoint until processing is complete
  </ParamField>

  <ParamField query="customIdentifier" type="string | null">
    Specify a custom identifier for the document. This may be your internal identifier. Does not need to be unique.
  </ParamField>

  <ParamField query="fileName" type="string | null">
    The optional filename of the file. If not specified, uses existing filename.
  </ParamField>

  <ParamField query="expiryTime" type="date-time">
    The date/time in ISO-8601 format when the document will be automatically deleted. Defaults to no expiry. See [Data Retention](/data-retention) for more information.
  </ParamField>

  <ParamField query="rejectDuplicates" type="boolean | null">
    If "true", parsing will fail when the uploaded document is a duplicate of an existing document; no credits will be consumed. If "false", will parse the document normally, whether it is a duplicate or not. If not provided, will fallback to the workspace settings.
  </ParamField>

  <ParamField query="lowPriority" type="boolean">
    Explicitly mark this document as low priority.
  </ParamField>

  <ParamField query="compact" type="boolean">
    If true, the returned parse result (assuming wait is also true) will be a compact version of the full result.
  </ParamField>

  <ParamField query="deleteAfterParse" type="boolean">
    If true, no data will be stored after parsing. Only compatible with requests where wait: True.
  </ParamField>

  <ParamField query="enableValidationTool" type="boolean">
    If true, the document will be viewable in the Affinda Validation Tool. Set to False to optimize parsing speed
  </ParamField>
</Expandable>