> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traddocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Document

> Submit a document to this endpoint, which will categorize it into the correct document type. It then returns the document split into its respective type and provides the extracted key-value pairs of essential information for each categorized document.

## Analyze Document Endpoint

The `Analyze Document` endpoint processes and analyzes multiple documents to extract important information. Here's a detailed breakdown of its functionality:

1. **Document Splitting**:
   The endpoint splits the provided documents into the appropriate types using a document splitter.

2. **Information Extraction**:
   The endpoint extracts key-value pairs of important information from each split document.

### Supported document types

* [Bill of Lading](../types/bill-of-lading)
* [Letter of Credit](../types/letter-of-credit)
* [Document Instruction](../types/document-instruction)
* [Contract](../types/contract)
* [Commercial Invoice](../types/commercial-invoice)
* [Packing List](../types/packing-list)
* [Certificate of Origin](../types/certificate-of-origin)
* [Certificate of Weight](../types/certificate-of-weight)
* [Certificate of Quality](../types/certificate-of-quality)
* [Phytosanitary Certificate](../types/phytosanitary-certificate)
* [Fumigation Certificate](../types/fumigation-certificate)
* More to come...

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.traddocs.com/v1/documents/analyze \
    --header 'Content-Type: multipart/form-data' \
    --header 'x-api-key: <api-key>' \
    --form file=@your/path/sample.pdf \
    --form url=https://url_to_your_document.pdf
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.traddocs.com/v1/documents/analyze"
  headers = {"x-api-key": "<api-key>"}
  files = {"file": open("your/path/sample.pdf", "rb")}
  // files = {"url": (None, "https://url_to_your_document.pdf")}

  response = requests.post(url, headers=headers, files=files)

  print(response.json())
  ```
</RequestExample>


## OpenAPI

````yaml POST /v1/documents/analyze
openapi: 3.1.0
info:
  title: Document API
  version: 1.0.0
servers:
  - url: https://api.traddocs.com
security:
  - ApiKeyAuth: []
paths:
  /v1/documents/analyze:
    post:
      description: >-
        Submit a document to this endpoint, which will categorize it into the
        correct document type. It then returns the document split into its
        respective type and provides the extracted key-value pairs of essential
        information for each categorized document.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentAnalyze'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentAnalyzeResponse'
        4XX:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DocumentAnalyze:
      title: DocumentAnalyze
      type: object
      description: >-
        Represents a request for document analysis. The object can contain
        either a file or a URL pointing to the document to be analyzed. The
        properties are mutually exclusive, meaning you should provide either a
        file or a URL, but not both.
      properties:
        file:
          type: string
          format: binary
          title: File
          description: >-
            A binary file representing the document to be analyzed. This should
            be provided as a file upload, for example using a
            multipart/form-data request. The file can be in various formats such
            as .pdf, .docx, .eml, etc. Example usage: -F
            'files=@path/to/your-document.extension'.
        url:
          type: string
          minLength: 1
          format: uri
          title: Url
          description: >-
            A URI pointing to the document to be analyzed. This should be used
            if the document is hosted at a specific URL and can be accessed
            directly from the web.
    DocumentAnalyzeResponse:
      title: DocumentAnalyzeResponse
      type: array
      items:
        type: object
        properties:
          split:
            type: object
            properties:
              document_type:
                type: string
                description: The type of document determined by the categorization process.
              pages:
                type: array
                items:
                  type: integer
                description: The pages that have been identified for this document type.
            description: >-
              Details of how the document has been split into its respective
              type and the associated pages.
          extracted:
            type: object
            description: >-
              The key-value pairs of essential information extracted from the
              document.
        description: >-
          An array of objects representing the split documents and their
          extracted information.
      description: >-
        The JSON response format for each document type can be referenced
        [here](../../../endpoints/document/types/bill-of-lading). By using this
        endpoint, you can efficiently manage and process multiple documents,
        obtaining structured and relevant information from them.
    Error:
      required:
        - detail
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````