Skip to main content
Batch Search allows you to process hundreds or thousands of Business Searches at once via CSV upload. It’s the fastest way to onboard large customer lists, refresh existing portfolios, or prepare businesses for Portfolio Monitoring at scale. This guide covers how to run batch searches through the Console and check their status by API. For understanding individual Business Search results, see Business Search: Basics. For adding businesses to monitoring after verification, see Portfolio Monitoring.

Prerequisites

Before running a batch search, ensure you have:

1. What Batch Search Does

When you run a Batch Search, Baselayer:
  • Processes each business in your CSV file as an individual search
  • Applies any selected add-ons (Enhanced Search, Industry, Website Analysis, PEP)
  • Optionally adds all results to Portfolio Monitoring
  • Returns results asynchronously as searches complete
  • Stores the full batch record for later review
Batch Search is ideal for:
  • Migrating an existing book of business
  • Periodic refreshes of a vendor or customer list
  • Running KYB on large lead pipelines
  • Preparing large sets of customers for Portfolio Monitoring

2. Running a Batch Search in the Console

Navigate to:
Console → Batch Search → Upload CSV
You will be asked to:
  • Upload a CSV file (up to 40,000 rows)
  • Provide a batch name
  • (Optional) Add all businesses to your Portfolio
  • (Optional) Monitor all businesses
  • (Optional) Add results to a specific Portfolio Group
  • (Optional) Enable Enhanced Search, Industry, Website Analysis, or PEP checks
Your selections apply to every row in the CSV. Important: Batch searches are asynchronous.
Baselayer provisions additional backend resources to handle large jobs.
This means:
  • Most batches begin running within ~3 minutes
  • Larger batches may take up to 10 minutes to start

3. Checking Batch Status via API

Query batch progress:

4. CSV Format Requirements

Your CSV must follow the official Baselayer schema exactly.
The example CSV provided in the Console shows all allowed columns and formatting rules.
Required columns:
  • legal_entity_name - Business legal name
  • legal_entity_address - Full business address
Optional columns:
  • tin - Business EIN/TIN (enables IRS verification)
  • website - Business website URL
  • officer_names - Semicolon-separated list of officers
  • phone_number - Business phone number
  • email - Business email
  • reference_id - Your internal ID for this business
Critical formatting rules:
  • Do not change column headers
  • Do not add or remove columns
  • Do not reorder columns
  • Follow exact address formatting from the template
  • Use UTF-8 encoding
  • Maximum rows: 40,000
If any row’s input is malformed, the whole upload is rejected with an error that lists the rows to fix. Fix those rows and upload the file again.

5. Understanding Batch Execution Timing

Batch processing is a timed, asynchronous workflow. Baselayer automatically provisions compute resources for the batch. As a result:
  • Most batches start processing within 3 minutes
  • Very large uploads may take up to 10 minutes before processing begins
  • Execution time varies by number of rows and selected add-ons
You may safely close the Console or disconnect from the API - the batch will continue running.

6. Reviewing Batch Results

Console Review

Navigate to Search History → Batches in the Console to view:
  • Search status (completed, failed, pending)
  • Any add-ons applied (Industry, Website Analysis, PEP)
  • Basic results (number of searches and number of failed searches)
You’ll also find a download icon for completed batches. Clicking download generates a ZIP archive containing structured export files. The ZIP always includes:
  • business_search.csv – Core Business Search results
  • business_search.jsonl – Same data in JSON Lines format
  • README.txt – Documentation explaining each file and column structure
  • report.pdf – Summary report of the batch
If add-ons were selected, additional files are included:
  • website_analysis.csv / .jsonl – If Website Analysis was ordered
  • industry_prediction.csv / .jsonl – If Industry Prediction was ordered
  • reviews_and_socials.csv – If Reviews & Socials was ordered
Each file uses search_id as a shared key so you can join data across products.
Note: Enhanced Search runs together with Website Analysis and Industry Prediction, so their files are included too. Only files for products that were requested will appear in the export.

7. Best Practices

Before Running Your Batch

✅ Test with a small sample first - Upload 5-10 rows to verify formatting before submitting your full file ✅ Clean your data - Remove duplicates, standardize address formats, validate TINs before upload ✅ Use the exact template - Download fresh from Console for each batch to ensure you have the latest schema

During Batch Execution

✅ Don’t modify the batch - Once submitted, you cannot edit or cancel. Let it complete. ✅ Use Groups for segmentation - Upload different customer segments to different Portfolio Groups for cleaner monitoring ✅ Consider costs - Each row in your batch is billed as an individual Business Search, plus any add-ons selected

After Batch Completion

✅ Review failed items - Identify patterns in failures (common: address or TIN formatting issues) ✅ Store business_id - Map batch results to your internal systems for future reference ✅ Use batch monitoring to initialize portfolio - Enable monitoring during batch upload rather than adding businesses individually later

Automation

✅ Integrate with your CRM - Export customer lists directly to Baselayer’s batch format

8. Next Steps

Understand batch results: Enable monitoring for batches: Process batch results:

9. Summary

Batch Search enables large-scale Business Search execution through a single CSV upload. Use it to process thousands of businesses efficiently, add them to Portfolio Monitoring, and maintain consistent verification across your customer base. Key capabilities:
  • Console submission
  • Automatic portfolio addition
  • Monitoring enablement at scale
  • Add-on enrichments (Enhanced, Industry, Website, PEP)
  • Asynchronous processing with status tracking
For questions about batch limits, pricing, or optimization, contact your Baselayer account manager.