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

# Document Verification

> Use the Document Verification to run OCR extraction and automated cross-checks on lending documents tied to a specific loan application.

The Document Verification API is designed for workflows where every document upload is associated with a specific application. After you initialize a flow and upload files, Atlas runs OCR on each document and performs pairwise cross-checks — for example, comparing the dealer address on an invoice against the delivery order. You can retrieve results by polling the status endpoint or by receiving them via a webhook callback.

<Steps>
  <Step title="Generate a token">
    Exchange your credentials for a short-lived JWT. Pass `Client-Id` and `Client-Secret` as request headers.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.helloatlas.in/v3/verification/authtoken \
        -H "Client-Id: <your-client-id>" \
        -H "Client-Secret: <your-client-secret>"
      ```
    </CodeGroup>

    **Response**

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expires_in": 3600
    }
    ```

    Store the `access_token` — you will pass it as the `Token` header in all subsequent requests. Tokens expire after `expires_in` seconds (3600).
  </Step>

  <Step title="Initialize a flow">
    Create a flow that binds a set of documents to a single loan application. The `flow_uuid` returned here is the key you use for all downstream calls.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.helloatlas.in/v3/verification/flow/init \
        -H "Token: <access_token>" \
        -H "Content-Type: application/json" \
        -d '{
          "product_type": "PROD_CDL",
          "application_id": "12321321",
          "auth_url": "https://your-system.example.com/atlas/auth",
          "callback_url": "https://your-system.example.com/atlas/callback",
          "flow_params": {}
        }'
      ```
    </CodeGroup>

    | Field            | Required | Description                                                     |
    | ---------------- | -------- | --------------------------------------------------------------- |
    | `product_type`   | Yes      | Always `"PROD_CDL"` for the consumer durable lending flow       |
    | `application_id` | Yes      | Your internal loan application ID                               |
    | `auth_url`       | Yes      | URL Atlas calls to re-authenticate on your behalf               |
    | `callback_url`   | Yes      | Webhook URL where Atlas sends the final results                 |
    | `flow_params`    | No       | Additional key-value parameters passed through to your callback |

    **Response**

    ```json theme={null}
    {
      "flow_uuid": "ec57821d-d766-4e24-81ef-a2768094511b"
    }
    ```

    <Note>
      Save the `flow_uuid`. Every subsequent API call for this application must include this identifier.
    </Note>
  </Step>

  <Step title="Upload documents">
    Submit the document files associated with the flow. Each entry in `file_urls` pairs an S3-hosted file with a `document_id` that you define for tracking.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.helloatlas.in/v3/verification/multiupload \
        -H "Token: <access_token>" \
        -H "Content-Type: application/json" \
        -d '{
          "flow_uuid": "ec57821d-d766-4e24-81ef-a2768094511b",
          "file_urls": [
            {
              "file_url": "https://files.s3.ap-south-1.amazonaws.com/uploads/invoice.jpg",
              "document_id": "81a36d96-0c47-4cf1-8452-690a0ef8b6d6"
            },
            {
              "file_url": "https://files.s3.ap-south-1.amazonaws.com/uploads/delivery_order.jpg",
              "document_id": "aaa5c157-8f04-4190-912e-13017cb3b372"
            },
            {
              "file_url": "https://files.s3.ap-south-1.amazonaws.com/uploads/aadhaar.jpg",
              "document_id": "edbca5a8-2e8b-400b-aaeb-bf733fb3009c"
            }
          ]
        }'
      ```
    </CodeGroup>

    **Response** — one entry per uploaded file

    ```json theme={null}
    {
      "batch_id": "BATCH-30732-SIYKJ-20251121113228"
    }
    ```

    Each upload gets a `batch_id` for granular tracking.
  </Step>

  <Step title="Poll for status">
    Check whether processing is complete before attempting to fetch results.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X GET "https://api.helloatlas.in/v3/verification/status?flow_uuid=ec57821d-d766-4e24-81ef-a2768094511b" \
        -H "Token: <access_token>"
      ```
    </CodeGroup>

    **Response**

    ```json theme={null}
    {
      "upload_status": "SUCCESS",
      "processing_status": "SUCCESS",
      "crossheck_status": "COMPLETED",
      "master_status": "SUCCESS"
    }
    ```

    | Field               | Values                                                           | Meaning                          |
    | ------------------- | ---------------------------------------------------------------- | -------------------------------- |
    | `upload_status`     | `NOT_STARTED` · `IN_PROGRESS` · `SUCCESS` · `FAILED`             | Whether files have been ingested |
    | `processing_status` | `NOT_STARTED` · `IN_PROGRESS` · `SUCCESS` · `FAILED` · `PENDING` | OCR extraction progress          |
    | `crossheck_status`  | `NOT_STARTED` · `PENDING` · `COMPLETED`                          | Cross-check comparison progress  |
    | `master_status`     | `NOT_STARTED` · `IN_PROGRESS` · `SUCCESS` · `FAILED`             | Rolled-up overall status         |

    Poll every 5–10 seconds until `master_status` is `SUCCESS` or `FAILED` before calling the extracts endpoint.

    <Tip>
      If you registered a `callback_url` when initializing the flow, Atlas will POST the full results to that URL automatically when processing finishes — removing the need to poll.
    </Tip>
  </Step>

  <Step title="Retrieve results">
    Once `master_status` is `SUCCESS`, fetch the full OCR data and cross-checks.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X GET "https://api.helloatlas.in/v3/verification/extracts?flow_uuid=ec57821d-d766-4e24-81ef-a2768094511b" \
        -H "Token: <access_token>"
      ```
    </CodeGroup>

    **Response** — the full `CallbackData` payload

    ```json theme={null}
    {
      "flow_uuid": "c6a2ffd7-eb44-4d16-8b45-32adc2182a8b",
      "ocr_data": [
        {
          "data": {
            "document_type": "INVOICE",
            "customer_name": { "value": "Pashangh", "confidence_score": 0.9 },
            "customer_address": { "value": "C1002 Falcon Tower Mumbai", "confidence_score": 0.0 },
            "dealership_name": { "value": "Mobile Point", "confidence_score": 0.0 },
            "dealer_gst": { "value": "29SFWYT8463N1Z", "confidence_score": 0.0 },
            "total_invoice_amount": { "value": "", "confidence_score": 0.0 },
            "invoice_date": { "value": "23-10-2025", "confidence_score": 0.0 },
            "invoice_number": { "value": "4332", "confidence_score": 0.0 },
            "hypothecation": { "value": "yes", "confidence_score": 0.0 },
            "dealer_sign": { "value": "yes", "confidence_score": 0.0 },
            "dealer_stamp": { "value": "yes", "confidence_score": 0.0 }
          },
          "document_id": "edbca5a8-2e8b-400b-aaeb-bf733fb3009c",
          "error_code": "",
          "error_reason": ""
        },
        {
          "data": {
            "document_type": "IMEI_CLOSEUP_IMAGE",
            "model": { "value": "V2123", "confidence_score": 0.0 },
            "imei_number": { "value": ["36732632"], "confidence_score": 0.0 },
            "price": { "value": 30000, "confidence_score": 0.0 }
          },
          "document_id": "12ddef0b-35ac-451a-bb3e-08b95f63d741",
          "error_code": "",
          "error_reason": ""
        },
        {
          "data": {},
          "document_id": "8409e7d5-88be-4cd0-80ba-5a93c6619a85",
          "error_code": "UNRECOGNISED",
          "error_reason": "document not in list"
        },
        {
          "data": {
            "document_type": "ASSET_OPEN_BOX_IMAGE",
            "customer_present": { "value": "yes", "confidence_score": 0.0 },
            "number_of_faces_visible": { "value": 3, "confidence_score": 0.0 }
          },
          "document_id": "e23559fd-b92e-41dc-82c6-982f3b652fb2",
          "error_code": "INVALID_DOC",
          "error_reason": "multiple people"
        }
      ],
      "cross_checks": [
        {
          "source_doc": "DELIVERY_ORDER",
          "source_field_name": "dealer_address",
          "source_value": "D. No. 14-4-16, Anam Vari Street, Kapu Street, Abbai Reddy Complex, NELLORE. 524001",
          "target_doc": "INVOICE",
          "target_field_name": "dealer_address",
          "target_value": "D. No. 14-4-16, Anam Vari Street, Kapu Street, 524001",
          "similarity_score": 60,
          "name": "DEALER_ADDRESS"
        },
        {
          "source_doc": "DELIVERY_ORDER",
          "source_field_name": "customer_name",
          "source_value": "Pashangh",
          "target_doc": "INVOICE",
          "target_field_name": "customer_name",
          "target_value": "Pashangh Irani",
          "similarity_score": 90,
          "name": "CUSTOMER_NAME"
        },
        {
          "source_doc": "DELIVERY_ORDER",
          "source_field_name": "customer_delivery_address",
          "source_value": "D. No. 14-4-16, Anam Vari Street, Kapu Street, 524001",
          "target_doc": "INVOICE",
          "target_field_name": "customer_address",
          "target_value": "D. No. 14-4-16, Anam Vari Street, Kapu Street, 524001",
          "similarity_score": 90,
          "name": "CUSTOMER_DELIVERY_ADDRESS"
        },
        {
          "source_doc": "DELIVERY_ORDER",
          "source_field_name": "customer_mobile_number",
          "source_value": "8655126210",
          "target_doc": "INVOICE",
          "target_field_name": "mobile_number",
          "target_value": "8655126210",
          "similarity_score": 90,
          "name": "CUSTOMER_MOBILE_NUMBER"
        }
      ]
    }
    ```

    **Understanding the response**

    The `ocr_data` array contains one item per uploaded document. The `data` object structure varies by `document_type`. When `error_code` is non-empty (e.g. `UNRECOGNISED`, `INVALID_DOC`), the `data` object will be empty or partial. The `cross_checks` array contains pairwise comparisons between fields extracted from two different documents. Each entry includes the raw values from both sides and a `similarity_score` (0–100). A score of 90 or above generally indicates a strong match; scores below 70 warrant manual review.
  </Step>
</Steps>

## Using the callback instead of polling

When you set `callback_url` in the flow init request, Atlas sends a `POST` request to that URL with the same `CallbackData` payload shown above once all processing is complete. Your endpoint must return a `2xx` response to acknowledge receipt.

The callback approach is recommended for production integrations because it eliminates polling overhead and delivers results as soon as they are ready.

<Note>
  Atlas calls your `auth_url` to obtain a fresh token before posting the callback. Ensure this URL is reachable from Atlas's servers.
</Note>

## Tracking files with batch\_id and file\_uuid

Every file returned from `multiupload` carries two identifiers:

* **`batch_id`** — shared across all files in the same upload request. Use this to group and audit a batch of documents.
* **`file_uuid`** — unique per file. Use this to reference a specific document when contacting Atlas support or building audit trails.

Both identifiers are present in the `ocr_data` items returned from the extracts endpoint.