Atlas Flow API

Use the Atlas Flow API to run OCR extraction and automated cross-checks on lending documents tied to a specific loan application.

The Atlas Flow 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.

1. Generate a token

   Exchange your credentials for a short-lived JWT. Pass Client-Id and Client-Secret as request headers.

   curl

   curl -X POST https://api.helloatlas.in/v3/verification/authtoken \
     -H "Client-Id: <your-client-id>" \
     -H "Client-Secret: <your-client-secret>"
   

   Response

   {
     "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).

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

   curl

   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": {}
     }'
   

   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

   {
     "flow_uuid": "ec57821d-d766-4e24-81ef-a2768094511b"
   }
   

   Save the flow_uuid. Every subsequent API call for this application must include this identifier.

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

   curl

   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": "1"
         },
         {
           "file_url": "https://files.s3.ap-south-1.amazonaws.com/uploads/delivery_order.jpg",
           "document_id": "2"
         },
         {
           "file_url": "https://files.s3.ap-south-1.amazonaws.com/uploads/aadhaar.jpg",
           "document_id": "3"
         }
       ]
     }'
   

   Response — one entry per uploaded file

   {
     "batch_id": "BATCH-30732-SIYKJ-20251121113228"
   }
   

   Each upload gets a batch_id for granular tracking.

4. Poll for status

   Check whether processing is complete before attempting to fetch results.

   curl

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

   Response

   {
     "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.

   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.

5. Retrieve results

   Once master_status is SUCCESS, fetch the full OCR data and cross-checks.

   curl

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

   Response — the full CallbackData payload

   {
     "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": "2332d12323isbjnfijbg",
         "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": "2332d12323isbjnfijbg",
         "error_code": "",
         "error_reason": ""
       },
       {
         "data": {},
         "document_id": "",
         "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": "",
         "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.

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.

Atlas calls your auth_url to obtain a fresh token before posting the callback. Ensure this URL is reachable from Atlas’s servers.

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.